Add requirement to use X-Ray propagation for aws-sdk client calls

CHANGELOG.md

@@ -49,6 +49,8 @@ release.
   ([#3298](https://github.com/open-telemetry/opentelemetry-specification/pull/3298))
 - Rename `net.app.protocol.(name|version)` to `net.protocol.(name|version)`
   ([#3272](https://github.com/open-telemetry/opentelemetry-specification/pull/3272))
+- Add requirement to use X-Ray propagation as default for aws-sdk client calls.
+  ([#3212](https://github.com/open-telemetry/opentelemetry-specification/pull/3212))
 - Replace `http.flavor` with `net.protocol.(name|version)`
   ([#3272](https://github.com/open-telemetry/opentelemetry-specification/pull/3272))
 - Metric requirement levels are now stable

specification/compatibility/aws.md

@@ -0,0 +1,32 @@
+# Compatibility Considerations for AWS
+
+**Status**: [Experimental](../document-status.md)
+
+This document highlights compatibility considerations when interacting with AWS
+managed services using an aws-sdk, a third-party library, or a direct HTTP request.
+
+## Context Propagation
+
+When making outgoing calls to AWS managed services using an aws-sdk, a third-party
+library, or a direct HTTP request, an AWS service-supported propagation format MUST
+be used to add context propagation to HTTP headers on the outgoing request in order
+to propagate the context to services (AWS Lambda) indirectly triggered by such call.
+
+Instrumentation MAY allow a different propagator to be explicitly provided to
+the instrumentation, in which case the provided propagator MUST be used.
+
+Propagation headers MUST be added before the signature is calculated to prevent errors on signed requests.
+
+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](../trace/semantic_conventions/instrumentation/aws-lambda.md#sqs-event)
+doc for details on how this context propagation is consumed by Lambda instrumentation.)
+
+Additional propagation formats MAY be applied to individual request types that support arbitrary attributes such as `SqsMessage`.
+This can allow for transporting additional context that may not be supported by X-Ray, such as baggage or tracestate.
+Documentation SHOULD advise that doing so is subject to attribute limits and billing impacts.

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](../../../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](../../../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`.

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](../../../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`,