Maintenance: track fetch subsegments per request instead of juggling the active-segment slot in instrumentFetch

[dreamorosi]

Summary

The undici/fetch instrumentation in ProviderService.instrumentFetch() manages the lifecycle of HTTP subsegments by juggling the X-Ray SDK's active-segment slot: onRequestStart calls getSegment() -> addNewSubsegment() -> setSegment(subsegment), and onResponse/onError call getSegment() again - expecting to find that same subsegment - then close() and setSegment(subsegment.parent) to restore.

This only works if all three diagnostics-channel callbacks resolve the same context slot. That holds today because the SDK's Lambda mode has a single process-wide CLS context, but it silently breaks as soon as invocations get their own contexts: undici's request:headers/request:error events can fire on an async chain rooted in the connection (created by a previous invocation, carrying its context snapshot) rather than the request. During the investigation of #5434 we observed exactly this on a deployed Node.js 22 function using per-invocation contexts (captureAsyncFunc semantics) with keep-alive connections: onResponse resolved a different context, isHttpSubsegment() failed, the fetch subsegment was never closed nor its parent restored - the handler subsegment's open-children counter never reached zero, so the entire invocation's trace data was silently dropped (details).

Why is this needed?

The decorator path (captureAsyncFunc) already gives each invocation a nested CLS context today, so the decorator + fetch + connection-reuse combination is potentially exposed to the same failure under Lambda Managed Instances concurrency. It also becomes a hard blocker for adopting per-invocation context isolation when upstream lands (aws/aws-xray-sdk-node#760, middyjs/middy#1661): with the current slot-juggling, the fix for #5434 would trade wrong-attribution for dropped traces.

Fixing it is also independent of upstream: correlating each subsegment to its undici request object removes the dependency on context-slot stability entirely.

Which area does this relate to?

Tracer

Solution

In onRequestStart, associate the created subsegment with the undici request object (e.g. WeakMap<request, subsegment>) instead of parking it in the active-segment slot. onResponse/onError then retrieve it from the map - both callbacks already receive the request in the channel message - enrich, close, and delete the entry. The setSegment(subsegment)/setSegment(subsegment.parent) slot dance can likely be dropped entirely; if the active-subsegment behavior during the request is deemed part of the contract (e.g. for nested manual segments), it needs a separate look, but the close/enrich path must not depend on it.

Acknowledgment

• This request meets Powertools for AWS Lambda (TypeScript) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

Future readers

Please react with 👍 and your use case to help us understand customer demand.

[dreamorosi]

@svozza could you please check if this is something that your InvokeStore fix addresses or it's separate.

[svozza]

Good catch — confirmed, and worth being explicit: #5446 doesn't fix this, it's what makes it live. The three undici callbacks talk to each other through the active-segment slot, and that only works because today's Lambda-mode slot is process-wide — the exact property #5446 removes. Once the slot is invocation-scoped, a kept-alive connection's request:headers event fires on an async chain rooted in a previous invocation's context, onResponse resolves the wrong store, isHttpSubsegment() fails, and the subsegment never closes — so the open-children counter wedges and the whole trace drops. Wrong-attribution traded for dropped traces, as you said.

Honest caveat on my validation of #5446: the LMI e2e ran with tracing disabled and made no outbound calls, so this path was never exercised. The results stand for annotation/metadata attribution but say nothing about instrumentFetch under LMI.

The WeakMap<request, subsegment> approach is right and this should be done as a fast follow to #5446. Only open question is the one you flagged: whether the subsegment being active during the request is part of the contract (nested manual segments inside a fetch?). My instinct is to drop the slot dance entirely and let the enrich/close path depend only on the map — anyone relying on the active-segment behaviour mid-request is depending on something that was already broken under concurrency.