Add requirement to use X-Ray propagation for aws-sdk client calls (#3212)

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`.

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`,

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.)