diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 41ccb4cce5..c3895e534e 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -14,7 +14,8 @@ use cases. - [All triggers](#all-triggers) - * [AWS X-Ray Environment Span Link](#aws-x-ray-environment-span-link) + * [Determining the remote parent span context](#determining-the-remote-parent-span-context) + + [EventToCarrier in auto-instrumentation](#eventtocarrier-in-auto-instrumentation) - [API Gateway](#api-gateway) - [SQS](#sqs) * [SQS Event](#sqs-event) @@ -54,21 +55,31 @@ 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 +### Determining the remote parent span context -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. +Lambda does not have HTTP headers to read from and instead stores the headers it was invoked with (including any propagated context, etc.) as part of the invocation event. If using AWS X-Ray tracing then the trace context is instead stored in the Lambda environment. It is also possible that both options are populated at the same time, with different values. Finally it is also possible to propagate tracing information in a SQS message using the system attribute of the message `AWSTraceHeader`. -**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. +The lambda instrumentation MUST use a `EventToCarrier` to prepare a `Carrier` to be used by subsequent `TextMapPropagators`. -[Span Link]: https://opentelemetry.io/docs/concepts/signals/traces/#span-links +A `EventToCarrier` MUST implement the `Convert` operation to convert a lambda `Event` into a `Carrier`. + +The `Convert` operation MUST return a `Carrier` and MUST have the following parameters: + `Event` - the lambda event. + +The `EventToCarrier` used in the lambda instrumentation SHOULD be provided as a parameter during the initialization of this +instrumentation. This parameter MAY be provided by users that provide a implementation for the `EventToCarrier`. + +Lambda instrumentation MUST provide a default `EventToCarrier`, the `HttpEventToCarrier`, which populates the `Carrier` with the content of the http headers used to invoke the lambda function, when that is available. + +If no `EventToCarrier` is provided during the initialization of the lambda instrumentation, the `HttpEventToCarrier` MUST be used. + +**NOTE**: When instrumenting a Java AWS Lambda with an `EventToCarrier` that extracts the event from the lambda environment, this `EventToCarrier` SHOULD first try to parse the `X-Amzn-Trace-Id` out of the system property `com.amazonaws.xray.traceHeader` before checking and attempting to parse the environment variable `_X_AMZN_TRACE_ID`. + +#### EventToCarrier in auto-instrumentation + +In languages that support auto-instrumentation, the `EventToCarrier` used in the lambda instrumentation MAY be configured using the environment variable `OTEL_AWS_LAMBDA_EVENT_TO_CARRIER`. This environment variable MUST be set to the name of the `EventToCarrier` that will be used. + +The `HttpEventToCarrier` has name `http-headers`. ## API Gateway