This abstracts away our tracing channels consumption into a utility that:

• Activates a span for the tracing channel lifecycle
• Manages the span across the entire lifecycle
  • Sets errors on the error channel
  • Correctly ends the span at the correct timing whether the traced call is sync or async
• Allows span/error enrichment and overrides

This util can be consumed uniformly across all of our server-side runtimes, I will create a stacked PR that refactors our code to use it, showcasing Nitro, Redis, and Deno adoption of that util.

How Does it work

By adding a TracingChannelBinding getters on our AsyncContextStrategy (ACS) implementations that implements a pair of fields:

export interface TracingChannelBinding {
  asyncLocalStorage: unknown;
  getStoreWithActiveSpan: (span: Span) => unknown;
}

The exact return type doesn't matter as long as the ACS can use it to properly parent scopes and nested async contexts. We have two implementations so far:

1. Our own that uses the { scope, isolationScope } pair.
2. OTel that uses the OTel API context.

To illustrate this more, we can walk the round-trip:

1. getStoreWithActiveSpan(span) clones the current scope, returns { scope, isolationScope }.
2. The courier bindTracingChannelToSpan takes that opaque value and hands it to channel.start.bindStore. Under the hood the channel does `asyncLocalStorage.run(producedValue, () => …the traced operation…). The courier never checks the value, it just drops it into the right ALS.
3. Anywhere inside the traced async operation, Sentry's scope machinery calls getScopes() which is asyncStorage.getStore() will get the ALS instance the courier bound into. So getCurrentScope(), getIsolationScope(), and getActiveSpan() all resolve to the scope carrying our span. Any child span started in that operation parents to it. That's the nesting.

So there are three parties, not two:

• Producer (getStoreWithActiveSpan), ACS owns it, knows the shape, builds it.
• Courier (bindTracingChannelToSpan), opaque, it shouldn't know what's in there.
• Reader (getScopes/scope APIs) ACS owns, knows the shape, reads it back.

So it's pretty type safe given the courier never checks the value, which it shouldn't because there is no guarantee what the ACS has put on it. That's also why the OTel strategy can return a Context instead.

flowchart TB
    subgraph Strategy["async context strategy (per-runtime impl — owns the store shape)"]
        Producer["PRODUCE<br/>getStoreWithActiveSpan(span)<br/>clone scope + plant span<br/>→ ALS impl: { scope, isolationScope }<br/>→ OTel impl: Context"]
        Reader["READ<br/>getScopes() / getCurrentScope()<br/>getActiveSpan()<br/>reads store back out"]
    end

    ALS["AsyncLocalStorage (binding.asyncLocalStorage)<br/>the shared pipe — same instance on both sides"]

    Courier["COURIER — bindTracingChannelToSpan<br/>strategy-blind, never inspects (TValue = unknown)<br/>channel.start.bindStore(binding.asyncLocalStorage, data ⇒ getStoreWithActiveSpan(span))"]

    Op["traced async operation<br/>start child span → parents to bound span ✓"]

    Producer -->|"produced store"| ALS
    Courier -->|"als.run(store, op)"| ALS
    ALS -->|"als.getStore()"| Op
    Op -.->|"getCurrentScope / getActiveSpan"| Reader
    Reader -.->|"resolves to scope carrying our span"| Op

Lifecycle Management

After testing across several node releases (20 -> 26), I locked down the strategy that we can rely on to make this reliable and predictable.

1. always start at start lifecycle event, this is emitted always and is reliable.
2. Use error For capturing exceptions and setting error span status, always reliable.
3. When end is emitted:
   1. If error is present on the context object, end the span immediatly, there won’t be any async events coming up, the function threw in the sync part, so there is no async part to execute.
   2. If result is present on the context object, end the span immediately, there won’t be any async events coming up. The function returned in the sync part or is sync trace itself. Use in or hasOwnProperty , Do not use undefined checks as the function can return nothing.
   3. Otherwise NO-OP, there is an async lifecycle events coming up.
4. When asyncStart is emitted: Do nothing, this event has no value for us.
5. When asyncEnd is emitted: Just end the span.