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