diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 59b38229a..aab4165ac 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -109,6 +109,7 @@ For every message in the event, the [message system attributes][] (not message a the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be parsed from the value of the attribute using the [AWS X-Ray Propagator](../../../context/api-propagators.md) and added as a link to the span. This means the span may have as many links as messages in the batch. +See [compatibility](../../../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info. - [`faas.trigger`][faas] MUST be set to `pubsub`. - [`messaging.operation`](../messaging.md) MUST be set to `process`. @@ -122,6 +123,7 @@ corresponding to the SQS event. The [message system attributes][] (not message a the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be parsed from the value of the attribute using the [AWS X-Ray Propagator](../../../context/api-propagators.md) and added as a link to the span. +See [compatibility](../../../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info. - [`faas.trigger`][faas] MUST be set to `pubsub`. - [`messaging.operation`](../messaging.md#messaging-attributes) MUST be set to `process`. diff --git a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md index 35b177277..ba179651f 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md @@ -9,6 +9,10 @@ are found. Some descriptions are also provided for populating general OpenTelemetry semantic conventions based on these APIs. +## Context Propagation + +See [compatibility](../../../../supplementary-guidelines/compatibility/aws.md#context-propagation). + ## Common Attributes The span name MUST be of the format `Service.Operation` as per the AWS HTTP API, e.g., `DynamoDB.GetItem`, diff --git a/supplementary-guidelines/compatibility/aws.md b/supplementary-guidelines/compatibility/aws.md new file mode 100644 index 000000000..c5091435d --- /dev/null +++ b/supplementary-guidelines/compatibility/aws.md @@ -0,0 +1,42 @@ +# Compatibility Considerations for AWS + +This document highlights compatibility considerations for OpenTelemetry +instrumentations when interacting with AWS managed services using an aws-sdk, +a third-party library, or a direct HTTP request. + +## Context Propagation + +When making calls to AWS managed services using an AWS SDK, a third-party +library, or a direct HTTP request, an AWS service-supported propagation format should +be used to add context propagation to HTTP headers on the outgoing request in order +to propagate the context to services indirectly invoked by such call. + +Instrumentation may allow a different propagator to be explicitly configured for +the instrumentation (e.g. an explicitly provided propagator, or an option to use the +globally configured propagator for all or certain calls). +This will be useful for certain cases where the services allow transporting these +headers to a receiving side, for example SQS or SNS with message attributes. +Note that this also means that instrumentations providing this option cannot just +replace their call to the X-Ray propagator with a call to another propagator (as +that would only send HTTP headers in the API REST call that would be immediately +ignored by the receiving AWS service), but will need to introduce per-service-call +implementations where it makes sense (e.g., for SQS send and SQS receive). +This can allow for transporting additional context that may not be supported by X-Ray, +such as baggage or tracestate, or supporting certain legacy propagation formats. +Documentation should advise that doing so is subject to attribute limits and billing impacts. + +Propagation headers must be added before the signature is calculated to prevent +errors on signed requests. If injecting into the request itself (not just adding +additional HTTP headers), additional considerations may apply (for example, the +.NET AWS SDK calculates a hash of the attributes it sends and compares it with +the `MD5OfMessageAttributes` that it receives). + +The following formats are currently natively supported by AWS services for propagation: + +* [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html) + +AWS service-supported context propagation is necessary to allow context propagation +through AWS managed services, for example: `S3 -> SNS -> SQS -> Lambda`. + +(See the [aws-lambda sqs-event semantic convention](../../specification/trace/semantic_conventions/instrumentation/aws-lambda.md#sqs-event) +doc for details on how this context propagation is consumed by Lambda instrumentation.)