feat(tracing): propagate environment attributes

[hassiebp]

Summary

• add an optional environment field to propagateAttributes
• validate and propagate it as the first-class langfuse.environment OpenTelemetry attribute
• support asBaggage, nested-scope restoration, and precedence over the span processor default
• document the public API and add focused integration coverage

Why

JavaScript users could set an environment directly on an observation, but could not set one once per request and have it inherited by later spans. This closes the verified parity gap with the Python SDK for shared proxies and multi-environment workloads.

Linear: LFE-14512

Impacted packages

• @langfuse/core
• @langfuse/tracing

Validation

• TURBO_CACHE_DIR=/private/tmp/langfuse-js-lfe-14512-turbo-cache pnpm build
• pnpm vitest run --project=integration tests/integration/propagation.integration.test.ts (75 passed)
• pnpm lint
• pnpm typecheck
• pnpm format:check
• repository pre-commit checks

Greptile Summary

This PR adds request-scoped environment propagation to the tracing API.

• Adds validation and OpenTelemetry context/baggage mapping for langfuse.environment.
• Ensures propagated environments override processor defaults and restore across nested scopes.
• Documents the new public option and adds focused integration coverage.

Confidence Score: 5/5

The PR appears safe to merge with no actionable defects identified in the changed behavior.

Environment values are consistently validated before entering or leaving propagation context, mapped to the canonical span attribute and baggage key, and applied after the processor default so request-scoped values take precedence.

_{Reviews (1): Last reviewed commit: "feat(tracing): propagate environment att..." | Re-trigger Greptile}

Context used:

• Knowledge Base — @langfuse/core: shared primitives for the SDK
• Knowledge Base — @langfuse/tracing: OTel-based observation instrumentation

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
langfuse-js	Ready	Preview	Jul 27, 2026 12:44pm

[github-actions]

@claude review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1830a70f5b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

LGTM — straightforward, well-tested addition that mirrors the existing propagation pattern.

Extended reasoning...

Overview

This PR adds an optional environment field to propagateAttributes in packages/core/src/propagation.ts, validating it (lowercase alphanumeric + hyphen/underscore, ≤40 chars, must not start with langfuse) and propagating it as the first-class langfuse.environment span attribute, with support for baggage-based cross-service propagation and nested-scope restoration. Also updates README docs and adds focused integration tests.

Security risks

None of note. The new validation regex is anchored and tested against edge cases (empty string, mixed case, invalid chars, over-length, langfuse-prefixed). Baggage propagation already carries a documented security warning (values go into outbound HTTP headers), and the environment value goes through the same validation whether it originates from direct params or baggage restoration.

Level of scrutiny

Low-to-moderate. The change touches shared core code (@langfuse/core) used across packages, but it strictly follows the exact established pattern used for traceName/version (same validation helper shape, same context-key/span-key/baggage-key switch additions, same setPropagatedAttribute plumbing). I verified in packages/otel/src/span-processor.ts that the span processor spreads propagatedAttributes after the default ENVIRONMENT attribute, so propagated environment correctly overrides the processor default as claimed — this part of the codebase was not touched by the diff and works correctly with the new code.

Other factors

Test coverage is thorough: validation edge cases, baggage round-tripping, nested-scope override/restore, and interaction with the processor default are all covered (75 passing integration tests per the PR description). The bug-hunting pass found no issues, and the two candidate issues it raised (about environment being overridden inside experiment context) concern pre-existing, unrelated code paths (the experiment-forces-sdk-experiment-environment override existed before this diff) rather than a defect introduced by this PR.