From 67fdf2a4e7a69fdbcc784c9984eeb82604e7d6b8 Mon Sep 17 00:00:00 2001 From: Anthony J Mirabella Date: Mon, 21 Aug 2023 17:32:38 -0400 Subject: [PATCH 1/4] FaaS: Change requirements regarding handling of AWS Lambda-provided `SpanContext` Signed-off-by: Anthony J Mirabella --- CHANGELOG.md | 2 ++ docs/faas/aws-lambda.md | 24 ++++++++++++------------ 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 006acac363..347af5a117 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -57,6 +57,8 @@ release. ([#60](https://github.com/open-telemetry/semantic-conventions/pull/60)) - BREAKING: Remove pluralization from JVM metric namespaces. ([#252](https://github.com/open-telemetry/semantic-conventions/pull/252)) +- FaaS: Change requirements regarding handling of AWS Lambda-provided `SpanContext` + ([#277](https://github.com/open-telemetry/semantic-conventions/pull/277)) ## v1.21.0 (2023-07-13) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 41ccb4cce5..cc2a9d0208 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 Environment Span Link +### AWS X-Ray Environment `SpanContext` -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.22.0/specification/context/api-propagators.md). If the -resulting `Context` is [valid](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.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.22.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. +If the `_X_AMZN_TRACE_ID` environment variable is set, instrumentation MUST ensure that the value from that +environment variable is included in the `Carrier` used to extract a parent `Context` with the `Field` name +"X-Amzn-Trace-Id" unless the `Carrier` already includes a value for that `Field`. -**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. +Instrumentation MUST provide users with the option to create a `Link` to the AWS Lambda vended spans. If this +option is enabled then the instrumentation MUST attempt to extract a `SpanContext` from a `Carrier` including +only the value of the `_X_AMZN_TRACE_ID` environment variable in a `Field` with the name "X-Amzn-Trace-Id". If +a valid `SpanContext` is extracted then it MUST be included as a `Link` in the initial span created by the +instrumentation. The `Link` MUST have an associated `String`-typed +attribute with a key of `source` and a value of `x-ray-env`, in order to indicate the source of the linked span. -[Span Link]: https://opentelemetry.io/docs/concepts/signals/traces/#span-links +**Note**: When instrumenting a Java AWS Lambda function, instrumentation SHOULD first try to obtain a value +from the system property `com.amazonaws.xray.traceHeader` before checking the `_X_AMZN_TRACE_ID` environment variable. ## API Gateway From 23ed268f39a4c6597abf2c9fb33079d465cdfa8a Mon Sep 17 00:00:00 2001 From: Anthony J Mirabella Date: Mon, 21 Aug 2023 17:39:38 -0400 Subject: [PATCH 2/4] run `mardown-toc` Signed-off-by: Anthony J Mirabella --- 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 cc2a9d0208..5e64a62deb 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 Environment `SpanContext`](#aws-x-ray-environment-spancontext) - [API Gateway](#api-gateway) - [SQS](#sqs) * [SQS Event](#sqs-event) From 90a5141d5ff42fbae62de649be8be96dde808dc6 Mon Sep 17 00:00:00 2001 From: Anthony J Mirabella Date: Tue, 22 Aug 2023 15:25:15 -0400 Subject: [PATCH 3/4] Change X-Ray environment variable handling to overlay on carrier Signed-off-by: Anthony J Mirabella --- 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 5e64a62deb..d50f5456f3 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -58,7 +58,7 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a If the `_X_AMZN_TRACE_ID` environment variable is set, instrumentation MUST ensure that the value from that environment variable is included in the `Carrier` used to extract a parent `Context` with the `Field` name -"X-Amzn-Trace-Id" unless the `Carrier` already includes a value for that `Field`. +"X-Amzn-Trace-Id". Instrumentation MUST provide users with the option to create a `Link` to the AWS Lambda vended spans. If this option is enabled then the instrumentation MUST attempt to extract a `SpanContext` from a `Carrier` including From 327e55f05606814ca2780b665bac7dab226779c7 Mon Sep 17 00:00:00 2001 From: Anthony J Mirabella Date: Tue, 29 Aug 2023 19:46:53 -0400 Subject: [PATCH 4/4] Remove reference to option for creating a link from Lambda execution environment context Signed-off-by: Anthony J Mirabella --- docs/faas/aws-lambda.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index d50f5456f3..23dcdd49d3 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -60,13 +60,6 @@ If the `_X_AMZN_TRACE_ID` environment variable is set, instrumentation MUST ensu environment variable is included in the `Carrier` used to extract a parent `Context` with the `Field` name "X-Amzn-Trace-Id". -Instrumentation MUST provide users with the option to create a `Link` to the AWS Lambda vended spans. If this -option is enabled then the instrumentation MUST attempt to extract a `SpanContext` from a `Carrier` including -only the value of the `_X_AMZN_TRACE_ID` environment variable in a `Field` with the name "X-Amzn-Trace-Id". If -a valid `SpanContext` is extracted then it MUST be included as a `Link` in the initial span created by the -instrumentation. The `Link` MUST have an associated `String`-typed -attribute with a key of `source` and a value of `x-ray-env`, in order to indicate the source of the linked span. - **Note**: When instrumenting a Java AWS Lambda function, instrumentation SHOULD first try to obtain a value from the system property `com.amazonaws.xray.traceHeader` before checking the `_X_AMZN_TRACE_ID` environment variable.