Correctly propagate the trace ID

[sebsto]

Issue

#633

Description of changes

The trace ID from AWS wasn't being propagated in a way that's accessible to the full async task tree. Tracing libraries like OpenTelemetry need the trace ID without requiring an explicit LambdaContext reference, and the old approach of only setting the _X_AMZN_TRACE_ID environment variable doesn't work safely in multi-concurrency mode since env vars are process-global.

This change adds a @TaskLocal static property LambdaContext.currentTraceID that the runtime sets before calling the handler. It's automatically available to all code in the handler's async task tree, including child tasks and background work.

In single-concurrency mode, the runtime still sets and clears the _X_AMZN_TRACE_ID env var for backward compatibility with legacy tooling. In multi-concurrency mode, only the TaskLocal is used to avoid races between concurrent invocations.

The runLoop function now accepts an isSingleConcurrencyMode flag so it knows which strategy to use. Call sites in LambdaRuntime and LambdaManagedRuntime pass the appropriate value.

Tests cover TaskLocal scoping, child task inheritance, concurrent isolation between tasks, env var lifecycle in both modes, and coexistence of the static TaskLocal with the existing instance traceID property.

New/existing dependencies impact assessment, if applicable

No new dependencies were added to this change.

Conventional Commits

feat: propagate trace ID via TaskLocal for async task tree access

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[sebsto]

I think API Breakage test is a false positive as the function has package access. It's not part of the public API

[Copilot]

Pull request overview

This PR implements trace ID propagation using Swift's TaskLocal mechanism to support OpenTelemetry and other tracing libraries that need access to the trace ID without requiring an explicit LambdaContext reference. The implementation maintains backward compatibility by continuing to set the _X_AMZN_TRACE_ID environment variable in single-concurrency mode while avoiding race conditions in multi-concurrency mode.

Changes:

• Added @TaskLocal static property LambdaContext.currentTraceID for implicit trace ID propagation through async task trees
• Modified handler invocation in Lambda.runLoop to wrap execution in a TaskLocal scope and conditionally manage the _X_AMZN_TRACE_ID environment variable based on concurrency mode
• Added isSingleConcurrencyMode parameter throughout the runtime call chain to control environment variable behavior

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
Sources/AWSLambdaRuntime/LambdaContext.swift	Added @TaskLocal static property currentTraceID with comprehensive documentation
Sources/AWSLambdaRuntime/Lambda.swift	Wrapped handler invocation in TaskLocal scope with conditional env var management; updated deprecation message
Sources/AWSLambdaRuntime/Runtime/LambdaRuntime.swift	Added isSingleConcurrencyMode parameter to runtime methods and threaded it through to Lambda.runLoop
Sources/AWSLambdaRuntime/ManagedRuntime/LambdaManagedRuntime.swift	Passes isSingleConcurrencyMode: false for multi-concurrency mode to avoid env var races
Tests/AWSLambdaRuntimeTests/LambdaRunLoopTests.swift	Updated test calls to include isSingleConcurrencyMode: true parameter
Tests/AWSLambdaRuntimeTests/LambdaTraceIDPropagationTests.swift	Comprehensive test suite covering TaskLocal behavior, env var lifecycle, concurrent isolation, and child task propagation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[manojmahapatra]

Question: so this is effectively writable by consumers, is this intended? Or currentTraceID need to be public read only (getter)?