Skip to content

Conversation

@enie123
Copy link

@enie123 enie123 commented Nov 30, 2025

What was changed

This PR migrates the @temporalio/interceptors-opentelemetry package from OpenTelemetry (OTel) v1.x to v2.x.

Core Changes:

  • Dependency Updates: Upgraded all @opentelemetry/* dependencies to compatible v2 versions.

Why?

Migration to OpenTelemetry V2

This PR uses BasicTracerProvider and avoids using NodeTracerProvider: #1741

The Reasoning:(LLM)

  1. Sandbox Constraints: Temporal Workflows run in a V8 Isolate (Sandbox) that is deterministic and patched to behave like a Browser environment (polyfilling window and performance). It explicitly removes Node.js globals like process and restricts access to native modules.
  2. The Crash Risk: NodeTracerProvider attempts to load async_hooks (a native Node module) to manage context. Since the sandbox blocks native modules, using NodeTracerProvider will cause the workflow to crash or behave non-deterministically. We must use BasicTracerProvider which is platform-agnostic.
  3. Context Propagation Fix: In OTel V1, BasicTracerProvider implicitly registered environment-based propagators. In OTel V2, this side effect was removed. As a result, trace context propagation was failing (generating fragmented traces for StartWorkflow -> RunWorkflow -> RunActivity).
    • Solution: This PR adds otel.propagation.setGlobalPropagator(new W3CTraceContextPropagator()) to manually restore the behavior required for the Sandbox to extract/inject headers correctly.

Checklist

  1. Closes: [Feature Request] Add support for opentelemetry v2 #1658

  2. How was this tested: pnpm test

@enie123 enie123 requested a review from a team as a code owner November 30, 2025 08:28
@CLAassistant
Copy link

CLAassistant commented Nov 30, 2025

CLA assistant check
All committers have signed the CLA.

@mjameswh
Copy link
Contributor

mjameswh commented Dec 1, 2025

Thanks a lot for offering this PR.

Unfortunately, we can't simply "upgrade" to OTel v2, as that would be a breaking change for all existing Temporal setups. The plan is therefore to make a new package for this, something like @temporalio/interceptors-opentelemetry2 (haven't made a final decision on the package name), so that both plugin versions can coexist.

Now, we're going through some heavy work to improve the completeness and DX on the OTel v1 interceptor at the moment. Those improvements will also be applicable to the v2, so much that it makes little sense to create the OTel v2 before we're done with present work on v1.

So the path forward will be, in proper order:

  1. Complete current efforts on covering all events through the OTel v1 interceptors
  2. Complete effort on extending the OTel interceptors v1 to the new Plugin form.
  3. Address serialization issues with the workflow/sink layer that are causing errors in some setups ([Bug] @temporalio/interceptors-opentelemetry OTEL bypasses a required SDK component #1779 and [Bug] opentelemetry traceState is handled properly in makeWorkflowExporter #1738).
  4. Duplicate the OTel v1 package to a new OTel v2 package, and adapt the code as needed.

In the mean time, you may use your own v2 copy of the OTel interceptors. There's really nothing here that requires that to be part of the official SDK.

I'll leave this PR open until then, so that other interested users may benefit from it.

@mjameswh mjameswh changed the title chore(otel): Migrate from v1 to v2 [HOLD] chore(otel): Migrate from v1 to v2 Dec 1, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature Request] Add support for opentelemetry v2

3 participants