From 07435bcc1fbc958fd9ee52a821989e3abeaa7c7f Mon Sep 17 00:00:00 2001 From: Anthony J Mirabella Date: Fri, 18 Aug 2023 14:34:27 -0400 Subject: [PATCH 1/2] FaaS: Clarify requirements regarding handling of AWS Lambda-provided `SpanContext Signed-off-by: Anthony J Mirabella --- CHANGELOG.md | 2 ++ docs/faas/aws-lambda.md | 30 ++++++++++++++++++------------ 2 files changed, 20 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 006acac363..84b2c7fe85 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: Clarify requirements regarding handling of AWS Lambda-provided `SpanContext` + ([#272](https://github.com/open-telemetry/semantic-conventions/pull/272)) ## v1.21.0 (2023-07-13) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 41ccb4cce5..60b0bd5306 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) @@ -54,19 +54,25 @@ 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 contains a non-empty value then instrumentation MUST attempt to extract an +OpenTelemetry `Context` from 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` contains a [valid `SpanContext`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#isvalid) then the +instrumentation MUST utilize it in one of the following ways when creating a `Span` representing the invocation (the `Invocation Span`): -**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. +* as the parent `Context` +* as a `SpanContext` associated with a [Span Link][] added to the `Invocation Span`'s +[start options](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#specifying-links) with 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. + +Instrumentation MUST provide a mechanism for the user to select the behavior that they require it to utilize. In the absence of an expressed user preference +instrumentation SHOULD utilize the extracted `Context` as the parent context for the `Invocation Span`. Instrumentation MAY require that the user explicitly +choose a behavior. + +**Note**: When instrumenting a Java AWS Lambda function, instrumentation SHOULD first try to extract an OpenTelemetry `Context` from 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 attempting to +extract a `Context` from the environment variable above. [Span Link]: https://opentelemetry.io/docs/concepts/signals/traces/#span-links From fc59e276bd51645dce03eac4f2f1a2cbb4b61c63 Mon Sep 17 00:00:00 2001 From: Anthony J Mirabella Date: Mon, 21 Aug 2023 11:27:45 -0400 Subject: [PATCH 2/2] update changelog to reflect requested change to change description Signed-off-by: Anthony J Mirabella --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 84b2c7fe85..6925553109 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -57,7 +57,7 @@ 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: Clarify requirements regarding handling of AWS Lambda-provided `SpanContext` +- FaaS: Change requirements regarding handling of AWS Lambda-provided `SpanContext` ([#272](https://github.com/open-telemetry/semantic-conventions/pull/272)) ## v1.21.0 (2023-07-13)