FaaS: Change requirements regarding handling of AWS Lambda-provided `…

…SpanContext`

Signed-off-by: Anthony J Mirabella <a9@aneurysm9.com>

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)
 

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