From 82e4bbbb4bf5f64d3906a7f1ae1c7d8de5d90af8 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 28 Sep 2023 17:14:05 -0400 Subject: [PATCH 01/15] Replace AWS X-Ray Environment Span Link section TC decided that users should be able to give priority (controlling the parent/child relationship) to AWS X-Ray's `Active Tracing` span context (as propagated via the `_X_AMZN_TRACE_ID` environment variable) by configuring a different order in the `OTEL_PROPAGATORS`. There is a separate effort to allow span contexts from additional propagators to be added as span links instead of just overwriting them. That will enable this previous behavior to be maintained. --- docs/faas/aws-lambda.md | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 50dba92033..c87410f6ca 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -14,7 +14,7 @@ use cases. - [All triggers](#all-triggers) - * [AWS X-Ray Environment Span Link](#aws-x-ray-environment-span-link) + * [AWS X-Ray `Active Tracing` Considerations](#aws-x-ray-active-tracing-considerations) - [API Gateway](#api-gateway) - [SQS](#sqs) * [SQS Event](#sqs-event) @@ -54,21 +54,28 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a [faasres]: /docs/resource/faas.md (FaaS resource conventions) [cloud]: /docs/resource/cloud.md (Cloud resource conventions) -### AWS X-Ray Environment Span Link +### AWS X-Ray `Active Tracing` Considerations -If the `_X_AMZN_TRACE_ID` environment variable is set, instrumentation SHOULD try to parse an -OpenTelemetry `Context` out of it using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/context/api-propagators.md). If the -resulting `Context` is [valid](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/trace/api.md#isvalid) then a [Span Link][] SHOULD be added to the new Span's -[start options](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/trace/api.md#specifying-links) with an associated attribute of `source=x-ray-env` to -indicate the source of the linked span. -Instrumentation MUST check if the context is valid before using it because the `_X_AMZN_TRACE_ID` environment variable can -contain an incomplete trace context which indicates X-Ray isn’t enabled. The environment variable will be set and the -`Context` will be valid and sampled only if AWS X-Ray has been enabled for the Lambda function. A user can -disable AWS X-Ray for the function if the X-Ray Span Link is not desired. +When AWS `Active Tracing` is enabled for a lambda, the runtime will automatically generate a span based on configured sampling rates and propagate the span context +via the `_X_AMZN_TRACE_ID` environment variable (and the `com.amazonaws.xray.traceHeader` system property for Java lambdas). This span context is encoded using +the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/context/api-propagators.md). -**Note**: When instrumenting a Java AWS Lambda, instrumentation SHOULD first try to parse an OpenTelemetry `Context` out of the system property `com.amazonaws.xray.traceHeader` using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md) before checking and attempting to parse the environment variable above. +Users MUST be able to configure the propagator to prioritize propagating the X-Ray `Active Tracing` span context. +(Users probably want this enabled if OpenTelemetry is configured to report spans to AWS X-Ray so their trace is linked together properly.) -[Span Link]: https://opentelemetry.io/docs/concepts/signals/traces/#span-links +Implementations MUST provide an additional propagator configurable as `xray-env` which ignores the given carrier instance and instead attempts to propagate +the span context from the `_X_AMZN_TRACE_ID` environment variable (and the `com.amazonaws.xray.traceHeader` system property for Java lambdas with priority given +to the system property if set). + +Since propagators are invoked in order, users would give priority to X-Ray's `Active Tracing` span context by setting the environment variable: + +`OTEL_PROPAGATORS=tracecontext,baggage,xray,xray-env` + +To avoid broken traces, if OpenTelemetry is reporting traces to another system besides AWS X-Ray, users should either omit `xray-env` or add it to the beginning: + +`OTEL_PROPAGATORS=xray-env,tracecontext,baggage,xray` + +*Note: The `trace-env` propagator can only `extract` context. The `inject` operation MUST be a no-op.* ## API Gateway From 551efc94e6b1283605ef92b4505b2ccfd84501e9 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Fri, 29 Sep 2023 12:24:45 -0400 Subject: [PATCH 02/15] Update changelog. --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index e7c4e4dcec..57aa9458e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ content of "Unreleased" section content will generate release notes for the release. ## Unreleased +- Replace AWS X-Ray Environment Span Link section with AWS X-Ray `Active Tracing` Considerations + ([#354](https://github.com/open-telemetry/semantic-conventions/pull/354)) ### Breaking From a0b93fa572d6a5f3c42530bd54a3ffcce2de4855 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Fri, 29 Sep 2023 14:16:48 -0400 Subject: [PATCH 03/15] Apply suggestions from code review Co-authored-by: Trask Stalnaker --- docs/faas/aws-lambda.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index c87410f6ca..dfd013498d 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -57,14 +57,14 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a ### AWS X-Ray `Active Tracing` Considerations When AWS `Active Tracing` is enabled for a lambda, the runtime will automatically generate a span based on configured sampling rates and propagate the span context -via the `_X_AMZN_TRACE_ID` environment variable (and the `com.amazonaws.xray.traceHeader` system property for Java lambdas). This span context is encoded using +via the `_X_AMZN_TRACE_ID` environment variable (and the `com.amazonaws.xray.traceHeader` system property for Java Lambda functions). This span context is encoded using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/context/api-propagators.md). Users MUST be able to configure the propagator to prioritize propagating the X-Ray `Active Tracing` span context. (Users probably want this enabled if OpenTelemetry is configured to report spans to AWS X-Ray so their trace is linked together properly.) Implementations MUST provide an additional propagator configurable as `xray-env` which ignores the given carrier instance and instead attempts to propagate -the span context from the `_X_AMZN_TRACE_ID` environment variable (and the `com.amazonaws.xray.traceHeader` system property for Java lambdas with priority given +the span context from the `_X_AMZN_TRACE_ID` environment variable (and the `com.amazonaws.xray.traceHeader` system property for Java Lambda functions with priority given to the system property if set). Since propagators are invoked in order, users would give priority to X-Ray's `Active Tracing` span context by setting the environment variable: From e77da20da555fd14dac4cca495831e4057e04f37 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Fri, 29 Sep 2023 14:24:20 -0400 Subject: [PATCH 04/15] Apply suggestions from code review --- docs/faas/aws-lambda.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index dfd013498d..23eb7c86ed 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -56,9 +56,10 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a ### AWS X-Ray `Active Tracing` Considerations -When AWS `Active Tracing` is enabled for a lambda, the runtime will automatically generate a span based on configured sampling rates and propagate the span context -via the `_X_AMZN_TRACE_ID` environment variable (and the `com.amazonaws.xray.traceHeader` system property for Java Lambda functions). This span context is encoded using -the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/context/api-propagators.md). +When [AWS `Active Tracing`](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html) is enabled for a lambda, +the runtime will automatically generate a span based on configured sampling rates and propagate the span context +via the `_X_AMZN_TRACE_ID` environment variable (and the `com.amazonaws.xray.traceHeader` system property for Java Lambda functions). +This span context is encoded using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/context/api-propagators.md). Users MUST be able to configure the propagator to prioritize propagating the X-Ray `Active Tracing` span context. (Users probably want this enabled if OpenTelemetry is configured to report spans to AWS X-Ray so their trace is linked together properly.) From e2513ea8a667ebd4ad7a6c16f906a09fab926e00 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Mon, 2 Oct 2023 16:11:51 -0400 Subject: [PATCH 05/15] Apply suggestions from code review Co-authored-by: Trask Stalnaker --- docs/faas/aws-lambda.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 23eb7c86ed..ce7d17e101 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -54,21 +54,21 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a [faasres]: /docs/resource/faas.md (FaaS resource conventions) [cloud]: /docs/resource/cloud.md (Cloud resource conventions) -### AWS X-Ray `Active Tracing` Considerations +### AWS X-Ray Active Tracing Considerations -When [AWS `Active Tracing`](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html) is enabled for a lambda, +When [AWS X-Ray Active Tracing](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html) is enabled for a lambda, the runtime will automatically generate a span based on configured sampling rates and propagate the span context via the `_X_AMZN_TRACE_ID` environment variable (and the `com.amazonaws.xray.traceHeader` system property for Java Lambda functions). This span context is encoded using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/context/api-propagators.md). -Users MUST be able to configure the propagator to prioritize propagating the X-Ray `Active Tracing` span context. +Users MUST be able to configure the propagator to prioritize propagating the X-Ray "Active Tracing" span context. (Users probably want this enabled if OpenTelemetry is configured to report spans to AWS X-Ray so their trace is linked together properly.) Implementations MUST provide an additional propagator configurable as `xray-env` which ignores the given carrier instance and instead attempts to propagate the span context from the `_X_AMZN_TRACE_ID` environment variable (and the `com.amazonaws.xray.traceHeader` system property for Java Lambda functions with priority given to the system property if set). -Since propagators are invoked in order, users would give priority to X-Ray's `Active Tracing` span context by setting the environment variable: +Since propagators are invoked in order, users would give priority to X-Ray's "Active Tracing" span context by setting the environment variable: `OTEL_PROPAGATORS=tracecontext,baggage,xray,xray-env` From 493d45ac69adb5c8889378a10ecc180b6470c70b Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Mon, 2 Oct 2023 16:37:04 -0400 Subject: [PATCH 06/15] Fix ToC --- CHANGELOG.md | 2 +- docs/faas/aws-lambda.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 57aa9458e7..d466861760 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ content of "Unreleased" section content will generate release notes for the release. ## Unreleased -- Replace AWS X-Ray Environment Span Link section with AWS X-Ray `Active Tracing` Considerations +- Replace AWS X-Ray Environment Span Link section with AWS X-Ray Active Tracing Considerations ([#354](https://github.com/open-telemetry/semantic-conventions/pull/354)) ### Breaking diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index ce7d17e101..46785e67f0 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -14,7 +14,7 @@ use cases. - [All triggers](#all-triggers) - * [AWS X-Ray `Active Tracing` Considerations](#aws-x-ray-active-tracing-considerations) + * [AWS X-Ray Active Tracing Considerations](#aws-x-ray-active-tracing-considerations) - [API Gateway](#api-gateway) - [SQS](#sqs) * [SQS Event](#sqs-event) From 7b494d61f19c5f9a39c7f15fe9c0b08676e37722 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Tue, 3 Oct 2023 12:52:54 -0400 Subject: [PATCH 07/15] Update docs/faas/aws-lambda.md Co-authored-by: Trask Stalnaker --- docs/faas/aws-lambda.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 46785e67f0..ac9ca4e421 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -56,7 +56,7 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a ### AWS X-Ray Active Tracing Considerations -When [AWS X-Ray Active Tracing](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html) is enabled for a lambda, +When [AWS X-Ray Active Tracing](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html) is enabled for a Lambda, the runtime will automatically generate a span based on configured sampling rates and propagate the span context via the `_X_AMZN_TRACE_ID` environment variable (and the `com.amazonaws.xray.traceHeader` system property for Java Lambda functions). This span context is encoded using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/context/api-propagators.md). From 57ae645f4782424da6d9a5a30bf101cc30f4812f Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 5 Oct 2023 12:05:45 -0400 Subject: [PATCH 08/15] `xray-env` -> `xray-lambda` --- docs/faas/aws-lambda.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index ac9ca4e421..1f853e99a2 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -64,17 +64,17 @@ This span context is encoded using the [AWS X-Ray Propagator](https://github.com Users MUST be able to configure the propagator to prioritize propagating the X-Ray "Active Tracing" span context. (Users probably want this enabled if OpenTelemetry is configured to report spans to AWS X-Ray so their trace is linked together properly.) -Implementations MUST provide an additional propagator configurable as `xray-env` which ignores the given carrier instance and instead attempts to propagate +Implementations MUST provide an additional propagator configurable as `xray-lambda` which ignores the given carrier instance and instead attempts to propagate the span context from the `_X_AMZN_TRACE_ID` environment variable (and the `com.amazonaws.xray.traceHeader` system property for Java Lambda functions with priority given to the system property if set). Since propagators are invoked in order, users would give priority to X-Ray's "Active Tracing" span context by setting the environment variable: -`OTEL_PROPAGATORS=tracecontext,baggage,xray,xray-env` +`OTEL_PROPAGATORS=tracecontext,baggage,xray,xray-lambda` -To avoid broken traces, if OpenTelemetry is reporting traces to another system besides AWS X-Ray, users should either omit `xray-env` or add it to the beginning: +To avoid broken traces, if OpenTelemetry is reporting traces to another system besides AWS X-Ray, users should either omit `xray-lambda` or add it to the beginning: -`OTEL_PROPAGATORS=xray-env,tracecontext,baggage,xray` +`OTEL_PROPAGATORS=xray-lambda,tracecontext,baggage,xray` *Note: The `trace-env` propagator can only `extract` context. The `inject` operation MUST be a no-op.* From f8b14e02b34d5abf6b0f3b3777e003a251b90314 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Tue, 10 Oct 2023 15:42:00 -0400 Subject: [PATCH 09/15] Update aws-lambda.md --- docs/faas/aws-lambda.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 1f853e99a2..f8fb10b648 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -76,7 +76,7 @@ To avoid broken traces, if OpenTelemetry is reporting traces to another system b `OTEL_PROPAGATORS=xray-lambda,tracecontext,baggage,xray` -*Note: The `trace-env` propagator can only `extract` context. The `inject` operation MUST be a no-op.* +*Note: The `trace-lambda` propagator can only `extract` context. The `inject` operation MUST be a no-op.* ## API Gateway From 80240e4d6df005b89abd7e825e991ccbbeecedec Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 12 Oct 2023 15:23:42 -0400 Subject: [PATCH 10/15] trace-lambda -> xray-lambda Fix a typo --- docs/faas/aws-lambda.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index f8fb10b648..b97bf0b847 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -76,7 +76,7 @@ To avoid broken traces, if OpenTelemetry is reporting traces to another system b `OTEL_PROPAGATORS=xray-lambda,tracecontext,baggage,xray` -*Note: The `trace-lambda` propagator can only `extract` context. The `inject` operation MUST be a no-op.* +*Note: The `xray-lambda` propagator can only `extract` context. The `inject` operation MUST be a no-op.* ## API Gateway From b7f68354ddd2682c646696db6e780bf2b4f1bc54 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 12 Oct 2023 16:10:20 -0400 Subject: [PATCH 11/15] Update CHANGELOG.md --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d466861760..5600b43da7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ content of "Unreleased" section content will generate release notes for the release. ## Unreleased + - Replace AWS X-Ray Environment Span Link section with AWS X-Ray Active Tracing Considerations ([#354](https://github.com/open-telemetry/semantic-conventions/pull/354)) From d8c78c0750c8869c19d693bcec548a6d7ec93b38 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 26 Oct 2023 14:37:19 -0400 Subject: [PATCH 12/15] Add clause to reduce propagator interference in problematic scenario. --- docs/faas/aws-lambda.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index b97bf0b847..f72aa2a59f 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -78,6 +78,8 @@ To avoid broken traces, if OpenTelemetry is reporting traces to another system b *Note: The `xray-lambda` propagator can only `extract` context. The `inject` operation MUST be a no-op.* +To avoid potential issues when extracting with an active span context, the `xray-lambda` propagator SHOULD check if the provided context already has an active span context. If found, the propagator SHOULD return the provided context unmodified. + ## API Gateway API Gateway allows a user to trigger a Lambda function in response to HTTP requests. It can be configured to be From 4cc4a4cd605e651a8cf2b8d40b6c470482cc6a23 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Mon, 11 Dec 2023 12:20:50 -0500 Subject: [PATCH 13/15] Code review fixes --- docs/faas/aws-lambda.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index f72aa2a59f..a7f693af56 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -59,14 +59,20 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a When [AWS X-Ray Active Tracing](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html) is enabled for a Lambda, the runtime will automatically generate a span based on configured sampling rates and propagate the span context via the `_X_AMZN_TRACE_ID` environment variable (and the `com.amazonaws.xray.traceHeader` system property for Java Lambda functions). -This span context is encoded using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/context/api-propagators.md). +This span context is encoded using the [X-Ray Tracing Header Format](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader). -Users MUST be able to configure the propagator to prioritize propagating the X-Ray "Active Tracing" span context. +Users MUST be able to configure the propagator to prioritize propagating this X-Ray "Active Tracing" span context. (Users probably want this enabled if OpenTelemetry is configured to report spans to AWS X-Ray so their trace is linked together properly.) -Implementations MUST provide an additional propagator configurable as `xray-lambda` which ignores the given carrier instance and instead attempts to propagate -the span context from the `_X_AMZN_TRACE_ID` environment variable (and the `com.amazonaws.xray.traceHeader` system property for Java Lambda functions with priority given -to the system property if set). +#### `xray-lambda` Propagator Functionality + +Implementations MUST provide an additional propagator configurable via the `OTEL_PROPAGATORS` environment variable setting as `xray-lambda`. +This propagator ignores the provided carrier instance and instead attempts to propagate the span context from the `_X_AMZN_TRACE_ID` environment variable +(and the `com.amazonaws.xray.traceHeader` system property for Java Lambda functions with priority given to the system property if set). + +To avoid potential issues when extracting with an active span context, the `xray-lambda` propagator SHOULD check if the provided context already has an active span context. If found, the propagator SHOULD return the provided context unmodified. + +#### `xray-lambda` Propagator Configuration Since propagators are invoked in order, users would give priority to X-Ray's "Active Tracing" span context by setting the environment variable: @@ -78,7 +84,6 @@ To avoid broken traces, if OpenTelemetry is reporting traces to another system b *Note: The `xray-lambda` propagator can only `extract` context. The `inject` operation MUST be a no-op.* -To avoid potential issues when extracting with an active span context, the `xray-lambda` propagator SHOULD check if the provided context already has an active span context. If found, the propagator SHOULD return the provided context unmodified. ## API Gateway From 1910d6ea0038ada0018b80d83ccde2808f4d6e91 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Mon, 11 Dec 2023 12:30:55 -0500 Subject: [PATCH 14/15] Fix linting --- docs/faas/aws-lambda.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index a7f693af56..d6978804dd 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -15,6 +15,8 @@ use cases. - [All triggers](#all-triggers) * [AWS X-Ray Active Tracing Considerations](#aws-x-ray-active-tracing-considerations) + + [`xray-lambda` Propagator Functionality](#xray-lambda-propagator-functionality) + + [`xray-lambda` Propagator Configuration](#xray-lambda-propagator-configuration) - [API Gateway](#api-gateway) - [SQS](#sqs) * [SQS Event](#sqs-event) @@ -84,7 +86,6 @@ To avoid broken traces, if OpenTelemetry is reporting traces to another system b *Note: The `xray-lambda` propagator can only `extract` context. The `inject` operation MUST be a no-op.* - ## API Gateway API Gateway allows a user to trigger a Lambda function in response to HTTP requests. It can be configured to be From 07a4cfebcc20c1f0f410f2e8d93d744effa02aa6 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 13 Dec 2023 17:31:29 -0500 Subject: [PATCH 15/15] More clarifications. --- docs/faas/aws-lambda.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index d6978804dd..c8a568b378 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -63,17 +63,33 @@ the runtime will automatically generate a span based on configured sampling rate via the `_X_AMZN_TRACE_ID` environment variable (and the `com.amazonaws.xray.traceHeader` system property for Java Lambda functions). This span context is encoded using the [X-Ray Tracing Header Format](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader). -Users MUST be able to configure the propagator to prioritize propagating this X-Ray "Active Tracing" span context. -(Users probably want this enabled if OpenTelemetry is configured to report spans to AWS X-Ray so their trace is linked together properly.) +Users MUST be able to [configure the propagator](#xray-lambda-propagator-configuration) to prioritize propagating this X-Ray "Active Tracing" span context. +(FYI: Users probably want this enabled if OpenTelemetry is configured to report spans to AWS X-Ray so their trace is linked together properly.) #### `xray-lambda` Propagator Functionality -Implementations MUST provide an additional propagator configurable via the `OTEL_PROPAGATORS` environment variable setting as `xray-lambda`. +SDK's that have instrumentation for AWS Lambda SHOULD provide an additional propagator alongside the X-Ray propagator +that can [be configured](#xray-lambda-propagator-configuration) via the `OTEL_PROPAGATORS` environment variable setting as `xray-lambda`. This propagator ignores the provided carrier instance and instead attempts to propagate the span context from the `_X_AMZN_TRACE_ID` environment variable (and the `com.amazonaws.xray.traceHeader` system property for Java Lambda functions with priority given to the system property if set). To avoid potential issues when extracting with an active span context, the `xray-lambda` propagator SHOULD check if the provided context already has an active span context. If found, the propagator SHOULD return the provided context unmodified. +Example pseudo implementation: + +``` +extract(context, carrier) { + if (Span.fromContext(context).getSpanContext().isValid()) + return context + + traceHeader = getEnvironment("_X_AMZN_TRACE_ID"); + if (isEmptyOrNull(traceHeader)) + return context + + return xrayPropagator.extract(context, ["_X_AMZN_TRACE_ID": traceHeader]) +} +``` + #### `xray-lambda` Propagator Configuration Since propagators are invoked in order, users would give priority to X-Ray's "Active Tracing" span context by setting the environment variable: