From 72ed38c8db8e07fcf04816d17b09eb7ab0cfe4af Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 1 Feb 2023 16:17:49 -0500 Subject: [PATCH 1/8] Update aws lambda spec to remove X-Ray Env propagation Per discussion in the FAAS SIG, we decided that the aws x-ray environment variable should be moved to a span link to avoid interfering with the configured propagators. We also decided that `EventToCarrier` should be specified in the spec to improve cross language instrumentation consistency. --- .../instrumentation/aws-lambda.md | 21 +++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index ac2726cfebe..38098880e99 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -61,22 +61,21 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a [faasres]: ../../../resource/semantic_conventions/faas.md (FaaS resource conventions) [cloud]: ../../../resource/semantic_conventions/cloud.md (Cloud resource conventions) -### Determining the parent of a span +### EventToCarrier -The parent of the span MUST be determined by considering both the environment and any headers or attributes -available from the event. +Each event type transmits propagation data inconsistently. Instrumentation SHOULD define a function that +takes the event as an argument and returns a carrier that can be passed into the configured propagators. -If the `_X_AMZN_TRACE_ID` environment variable is set, instrumentations SHOULD first try to parse an +### AWS X-Ray Environment Span Link + +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](../../../context/api-propagators.md). If the -resulting `Context` is [valid](../../api.md#isvalid) and sampled, then this `Context` is the parent of the -function span. We check if it is valid because sometimes the `_X_AMZN_TRACE_ID` environment variable contains +resulting `Context` is [valid](../../api.md#isvalid) then a span link should be added to the lambda span with +an associated attribute of `source=x-ray-env` to indicate what the link is for. +We check if it is valid because sometimes the `_X_AMZN_TRACE_ID` environment variable contains 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 X-Ray propagation is not desired. - -Otherwise, when X-Ray propagation fails, the user's configured propagators SHOULD be applied to the HTTP -headers of the request to extract a `Context`. For example, API Gateway proxy requests can be configured to -send HTTP headers to a Lambda function using [a body mapping template](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-override-request-response-parameters.html). +disable AWS X-Ray for the function if the X-Ray span link is not desired. ## API Gateway From af2298c0c1446dd3d787fc2fc50d68556ead3954 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 1 Feb 2023 16:56:38 -0500 Subject: [PATCH 2/8] Apply review suggestions. --- .../instrumentation/aws-lambda.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 38098880e99..765ee932fb4 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -63,17 +63,18 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a ### EventToCarrier -Each event type transmits propagation data inconsistently. Instrumentation SHOULD define a function that -takes the event as an argument and returns a carrier that can be passed into the configured propagators. +Each event type may represent propagation data in its own way. Instrumentation SHOULD support a user defined transform +function which takes the event as an argument and returns a carrier that can be passed into the configured propagators. +Instrumentation SHOULD provide default implementations for the standard event types. ### AWS X-Ray Environment Span Link 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](../../../context/api-propagators.md). If the resulting `Context` is [valid](../../api.md#isvalid) then a span link should be added to the lambda span with -an associated attribute of `source=x-ray-env` to indicate what the link is for. -We check if it is valid because sometimes the `_X_AMZN_TRACE_ID` environment variable contains -an incomplete trace context which indicates X-Ray isn’t enabled. The environment variable will be set and the +an associated attribute of `source=x-ray-env` to indicate the source of the linked span. +Instrumentation needs to check if the context is valid because the `_X_AMZN_TRACE_ID` environment variable may +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. From f8be2b635693769a4525e3e64cb1cf42a3eeb8ab Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 1 Feb 2023 17:09:09 -0500 Subject: [PATCH 3/8] Add links to links :-) Co-authored-by: Tristan Sloughter --- .../trace/semantic_conventions/instrumentation/aws-lambda.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 765ee932fb4..1b2e6b10ba7 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -71,7 +71,7 @@ Instrumentation SHOULD provide default implementations for the standard event ty 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](../../../context/api-propagators.md). If the -resulting `Context` is [valid](../../api.md#isvalid) then a span link should be added to the lambda span with +resulting `Context` is [valid](../../api.md#isvalid) then a [Span Link](https://opentelemetry.io/docs/concepts/signals/traces/#span-links) should be added to the new Span's [start options](../../api.md#specifying-links) with an associated attribute of `source=x-ray-env` to indicate the source of the linked span. Instrumentation needs to check if the context is valid because the `_X_AMZN_TRACE_ID` environment variable may contain an incomplete trace context which indicates X-Ray isn’t enabled. The environment variable will be set and the From 85c0d9d7d195512dda2c08185284e9fa2f6af804 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 1 Feb 2023 17:20:03 -0500 Subject: [PATCH 4/8] More review changes Pulled section about EventToCarrier for further discussion. --- .../instrumentation/aws-lambda.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 1b2e6b10ba7..2f4a86f2696 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -61,22 +61,19 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a [faasres]: ../../../resource/semantic_conventions/faas.md (FaaS resource conventions) [cloud]: ../../../resource/semantic_conventions/cloud.md (Cloud resource conventions) -### EventToCarrier - -Each event type may represent propagation data in its own way. Instrumentation SHOULD support a user defined transform -function which takes the event as an argument and returns a carrier that can be passed into the configured propagators. -Instrumentation SHOULD provide default implementations for the standard event types. - ### AWS X-Ray Environment Span Link 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](../../../context/api-propagators.md). If the -resulting `Context` is [valid](../../api.md#isvalid) then a [Span Link](https://opentelemetry.io/docs/concepts/signals/traces/#span-links) should be added to the new Span's [start options](../../api.md#specifying-links) with -an associated attribute of `source=x-ray-env` to indicate the source of the linked span. +resulting `Context` is [valid](../../api.md#isvalid) then a [Span Link][] should be added to the new Span's +[start options](../../api.md#specifying-links) with an associated attribute of `source=x-ray-env` to +indicate the source of the linked span. Instrumentation needs to check if the context is valid because the `_X_AMZN_TRACE_ID` environment variable may 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. +disable AWS X-Ray for the function if the X-Ray Span Link is not desired. + +[Span Link]: https://opentelemetry.io/docs/concepts/signals/traces/#span-links ## API Gateway From 54ef1a0d8d0b4a89e29d4e365366ed528e76ba28 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 1 Feb 2023 17:59:19 -0500 Subject: [PATCH 5/8] fix lint checks --- .../trace/semantic_conventions/instrumentation/aws-lambda.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 2f4a86f2696..44f5e3bbceb 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -14,7 +14,7 @@ use cases. - [All triggers](#all-triggers) - * [Determining the parent of a span](#determining-the-parent-of-a-span) + * [AWS X-Ray Environment Span Link](#aws-x-ray-environment-span-link) - [API Gateway](#api-gateway) - [SQS](#sqs) * [SQS Event](#sqs-event) @@ -65,7 +65,7 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a 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](../../../context/api-propagators.md). If the -resulting `Context` is [valid](../../api.md#isvalid) then a [Span Link][] should be added to the new Span's +resulting `Context` is [valid](../../api.md#isvalid) then a [Span Link][] should be added to the new Span's [start options](../../api.md#specifying-links) with an associated attribute of `source=x-ray-env` to indicate the source of the linked span. Instrumentation needs to check if the context is valid because the `_X_AMZN_TRACE_ID` environment variable may From 959dec9c73505b09da682ff127415a03772427be Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 8 Feb 2023 11:08:46 -0500 Subject: [PATCH 6/8] Update specification/trace/semantic_conventions/instrumentation/aws-lambda.md Co-authored-by: Tyler Yahn --- .../trace/semantic_conventions/instrumentation/aws-lambda.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 44f5e3bbceb..13c3e12d521 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -65,7 +65,7 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a 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](../../../context/api-propagators.md). If the -resulting `Context` is [valid](../../api.md#isvalid) then a [Span Link][] should be added to the new Span's +resulting `Context` is [valid](../../api.md#isvalid) then a [Span Link][] SHOULD be added to the new Span's [start options](../../api.md#specifying-links) with an associated attribute of `source=x-ray-env` to indicate the source of the linked span. Instrumentation needs to check if the context is valid because the `_X_AMZN_TRACE_ID` environment variable may From 73cfa1633236360550f002664226a5335fa5962d Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 8 Feb 2023 11:08:54 -0500 Subject: [PATCH 7/8] Update specification/trace/semantic_conventions/instrumentation/aws-lambda.md Co-authored-by: Tyler Yahn --- .../trace/semantic_conventions/instrumentation/aws-lambda.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 13c3e12d521..cad57ad0eca 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -68,7 +68,7 @@ OpenTelemetry `Context` out of it using the [AWS X-Ray Propagator](../../../cont resulting `Context` is [valid](../../api.md#isvalid) then a [Span Link][] SHOULD be added to the new Span's [start options](../../api.md#specifying-links) with an associated attribute of `source=x-ray-env` to indicate the source of the linked span. -Instrumentation needs to check if the context is valid because the `_X_AMZN_TRACE_ID` environment variable may +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. From 744bb9f73512814044746b6b16492c88f7c80369 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 9 Feb 2023 15:58:37 -0500 Subject: [PATCH 8/8] Add CHANGELOG entry. --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 844fd3d94ad..9a70e5f5c99 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,9 @@ release. ### Semantic Conventions +- Move X-Ray Env Variable propagation to span link instead of parent for AWS Lambda. + ([#3166](https://github.com/open-telemetry/opentelemetry-specification/pull/3166)) + ### Compatibility ### OpenTelemetry Protocol