From 204e26ed2e704c9d831cb38479051fc5e8534ee2 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 15 Feb 2023 15:47:26 -0500 Subject: [PATCH 01/15] Add requirement to use X-Ray propagation for aws-sdk client calls X-Ray is necessary because it is the only format currently supported by AWS to allow context propagation through AWS managed services, for example SNS -> SQS -> Lambda, or S3 -> Lambda. --- .../semantic_conventions/instrumentation/aws-sdk.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md index 73bc631638d..d8baef9c489 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md @@ -9,6 +9,16 @@ are found. Some descriptions are also provided for populating general OpenTelemetry semantic conventions based on these APIs. +## Context Propagation + +When making outgoing calls using an aws-sdk, AWS X-Ray's propagation format MUST be used to add context propagation +to http headers of the outgoing request. Propagation headers MUST be added before the signature is calculated +to prevent errors on signed requests. X-Ray is necessary because it is the only format currently supported by AWS to +allow context propagation through AWS managed services, for example SNS -> SQS -> lambda. Implementations of AWS X-Ray +instrumentation for aws-sdk can be used as reference for how to instrument the SDK for each language. +(For example: [java](https://github.com/aws/aws-xray-sdk-java), [node](https://github.com/aws/aws-xray-sdk-node), and +[python](https://github.com/aws/aws-xray-sdk-python).) + ## Common Attributes The span name MUST be of the format `Service.Operation` as per the AWS HTTP API, e.g., `DynamoDB.GetItem`, From f9cc5b3e95d1d2897510160102247f205e863e6b Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 16 Feb 2023 11:49:27 -0500 Subject: [PATCH 02/15] Add CHANGELOG entry and allow additional propagators. --- CHANGELOG.md | 2 ++ .../trace/semantic_conventions/instrumentation/aws-sdk.md | 4 ++++ 2 files changed, 6 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a70e5f5c99..3a3dd28b48f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,8 @@ release. - Move X-Ray Env Variable propagation to span link instead of parent for AWS Lambda. ([#3166](https://github.com/open-telemetry/opentelemetry-specification/pull/3166)) +- Add requirement to use X-Ray propagation for aws-sdk client calls. + ([#3212](https://github.com/open-telemetry/opentelemetry-specification/pull/3212)) ### Compatibility diff --git a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md index d8baef9c489..c2b88675e98 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md @@ -19,6 +19,10 @@ instrumentation for aws-sdk can be used as reference for how to instrument the S (For example: [java](https://github.com/aws/aws-xray-sdk-java), [node](https://github.com/aws/aws-xray-sdk-node), and [python](https://github.com/aws/aws-xray-sdk-python).) +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. +Documentation SHOULD advise that doing so is subject to attribute limits and billing impacts. + ## Common Attributes The span name MUST be of the format `Service.Operation` as per the AWS HTTP API, e.g., `DynamoDB.GetItem`, From ad17d8ef56d5d73de7f602d019b7f1e8ef7753fa Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 16 Feb 2023 13:12:16 -0500 Subject: [PATCH 03/15] Add tracestate as another example. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christian Neumüller --- .../trace/semantic_conventions/instrumentation/aws-sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md index c2b88675e98..9faea60eeff 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md @@ -20,7 +20,7 @@ instrumentation for aws-sdk can be used as reference for how to instrument the S [python](https://github.com/aws/aws-xray-sdk-python).) 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. +`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. ## Common Attributes From 4c5a56a291ea83842a4dae0f77647357386414ec Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 16 Feb 2023 13:22:26 -0500 Subject: [PATCH 04/15] Additional rewording per review Required reformatting... sorry for messing up the diff. --- .../instrumentation/aws-sdk.md | 21 ++++++++++--------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md index 9faea60eeff..97ca67b61ee 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md @@ -11,16 +11,17 @@ Some descriptions are also provided for populating general OpenTelemetry semanti ## Context Propagation -When making outgoing calls using an aws-sdk, AWS X-Ray's propagation format MUST be used to add context propagation -to http headers of the outgoing request. Propagation headers MUST be added before the signature is calculated -to prevent errors on signed requests. X-Ray is necessary because it is the only format currently supported by AWS to -allow context propagation through AWS managed services, for example SNS -> SQS -> lambda. Implementations of AWS X-Ray -instrumentation for aws-sdk can be used as reference for how to instrument the SDK for each language. -(For example: [java](https://github.com/aws/aws-xray-sdk-java), [node](https://github.com/aws/aws-xray-sdk-node), and -[python](https://github.com/aws/aws-xray-sdk-python).) - -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. +When making outgoing calls using an aws-sdk, AWS X-Ray's propagation format MUST be used to add context propagation to +http headers of the outgoing request. Propagation headers MUST be added before the signature is calculated to prevent errors +on signed requests. Instrumentations MAY offer an enabled-by-default option to control enabling/disabling X-Ray propagation. + +X-Ray is necessary because it is the only format currently supported by AWS to allow context propagation through AWS managed +services, for example SNS -> SQS -> Lambda. Implementations of AWS X-Ray instrumentation for aws-sdk can be used as +reference for how to instrument the SDK for each language. (For example: [java](https://github.com/aws/aws-xray-sdk-java), +[node](https://github.com/aws/aws-xray-sdk-node), and [python](https://github.com/aws/aws-xray-sdk-python).) + +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. ## Common Attributes From b135bad1384d13b1040e76b073c3e94840499e7f Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 22 Feb 2023 15:10:17 -0500 Subject: [PATCH 05/15] Apply suggestions from code review Co-authored-by: Anthony Mirabella --- CHANGELOG.md | 2 +- .../semantic_conventions/instrumentation/aws-sdk.md | 10 ++++------ 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9305e6b82de..3eb2bc084e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,7 +30,7 @@ release. ([#3209](https://github.com/open-telemetry/opentelemetry-specification/pull/3209)) - Add Connect RPC specific conventions ([#3116](https://github.com/open-telemetry/opentelemetry-specification/pull/3116)) -- Add requirement to use X-Ray propagation for aws-sdk client calls. +- Add requirement to use X-Ray propagation as default for aws-sdk client calls. ([#3212](https://github.com/open-telemetry/opentelemetry-specification/pull/3212)) ### Compatibility diff --git a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md index 97ca67b61ee..7370e69a198 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md @@ -11,14 +11,12 @@ Some descriptions are also provided for populating general OpenTelemetry semanti ## Context Propagation -When making outgoing calls using an aws-sdk, AWS X-Ray's propagation format MUST be used to add context propagation to -http headers of the outgoing request. Propagation headers MUST be added before the signature is calculated to prevent errors -on signed requests. Instrumentations MAY offer an enabled-by-default option to control enabling/disabling X-Ray propagation. +When making outgoing calls using an aws-sdk, an AWS service-supported propagation format MUST be used to add context propagation to +http headers of the outgoing request unless another propagator is explicitly provided. Propagation headers MUST be added before the signature is calculated to prevent errors +on signed requests. X-Ray is necessary because it is the only format currently supported by AWS to allow context propagation through AWS managed -services, for example SNS -> SQS -> Lambda. Implementations of AWS X-Ray instrumentation for aws-sdk can be used as -reference for how to instrument the SDK for each language. (For example: [java](https://github.com/aws/aws-xray-sdk-java), -[node](https://github.com/aws/aws-xray-sdk-node), and [python](https://github.com/aws/aws-xray-sdk-python).) +services, for example SNS -> SQS -> Lambda. 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. From adf69dc00a3dbb2bbe9b8aad003611587f2b448a Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 22 Feb 2023 15:26:42 -0500 Subject: [PATCH 06/15] Restructure and reformat. --- .../instrumentation/aws-sdk.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md index 7370e69a198..2e6fce27719 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md @@ -11,12 +11,16 @@ Some descriptions are also provided for populating general OpenTelemetry semanti ## Context Propagation -When making outgoing calls using an aws-sdk, an AWS service-supported propagation format MUST be used to add context propagation to -http headers of the outgoing request unless another propagator is explicitly provided. Propagation headers MUST be added before the signature is calculated to prevent errors -on signed requests. +When making outgoing calls using an aws-sdk, an AWS service-supported propagation format MUST be used to add +context propagation to http headers on the outgoing request, unless another propagator is explicitly provided. +Propagation headers MUST be added before the signature is calculated to prevent errors on signed requests. -X-Ray is necessary because it is the only format currently supported by AWS to allow context propagation through AWS managed -services, for example SNS -> SQS -> Lambda. +The following formats are currently 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. 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. From 319939b77471c49065e6ac545bf8a61c6ddbf80e Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Fri, 24 Feb 2023 16:28:00 -0500 Subject: [PATCH 07/15] Update specification/trace/semantic_conventions/instrumentation/aws-sdk.md Co-authored-by: Anthony Mirabella --- .../trace/semantic_conventions/instrumentation/aws-sdk.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md index 2e6fce27719..fc8f4d50ddd 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md @@ -12,7 +12,8 @@ Some descriptions are also provided for populating general OpenTelemetry semanti ## Context Propagation When making outgoing calls using an aws-sdk, an AWS service-supported propagation format MUST be used to add -context propagation to http headers on the outgoing request, unless another propagator is explicitly provided. +context propagation to HTTP headers on the outgoing request, unless another propagator is explicitly provided, +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 supported by AWS services for propagation: From 71b8989f6682e7b1c16cabf55d43b51ad2b5feef Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 1 Mar 2023 10:59:40 -0500 Subject: [PATCH 08/15] Update specification/trace/semantic_conventions/instrumentation/aws-sdk.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christian Neumüller --- .../trace/semantic_conventions/instrumentation/aws-sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md index fc8f4d50ddd..2d070a544a5 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md @@ -16,7 +16,7 @@ context propagation to HTTP headers on the outgoing request, unless another prop 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 supported by AWS services for propagation: +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) From 1969fa33afcbbfab59f8d1c2248c20bf3f382a83 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Fri, 3 Mar 2023 15:37:03 -0500 Subject: [PATCH 09/15] Move context propagation details to compatibility section --- specification/compatibility/aws.md | 27 +++++++++++++++++++ .../instrumentation/aws-lambda.md | 2 ++ .../instrumentation/aws-sdk.md | 16 +---------- 3 files changed, 30 insertions(+), 15 deletions(-) create mode 100644 specification/compatibility/aws.md diff --git a/specification/compatibility/aws.md b/specification/compatibility/aws.md new file mode 100644 index 00000000000..c3be2865c3b --- /dev/null +++ b/specification/compatibility/aws.md @@ -0,0 +1,27 @@ +# Compatibility Considerations for AWS + +**Status**: [Experimental](../document-status.md) + +This document highlights compatibility considerations when interacting with AWS managed services. + +## Context Propagation + +When making outgoing calls using an aws-sdk, an AWS service-supported propagation format MUST be used to add +context propagation to HTTP headers on the outgoing request, unless another propagator is explicitly provided, +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. + diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 34a1362edf4..a1f2cba0dae 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -116,6 +116,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`. @@ -129,6 +130,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`. diff --git a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md index 2d070a544a5..a70f08510bc 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md @@ -11,21 +11,7 @@ Some descriptions are also provided for populating general OpenTelemetry semanti ## Context Propagation -When making outgoing calls using an aws-sdk, an AWS service-supported propagation format MUST be used to add -context propagation to HTTP headers on the outgoing request, unless another propagator is explicitly provided, -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. - -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. +See [compatibility](../../../compatibility/aws.md#context-propagation). ## Common Attributes From e78230358563c7f6b68e24295b3875bff6c862ab Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 6 Apr 2023 11:51:46 -0400 Subject: [PATCH 10/15] Elaborate on a few items of concern from various reviews. Also improve formatting a bit. --- specification/compatibility/aws.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/specification/compatibility/aws.md b/specification/compatibility/aws.md index 09be2c4f302..afe76eb060d 100644 --- a/specification/compatibility/aws.md +++ b/specification/compatibility/aws.md @@ -2,13 +2,19 @@ **Status**: [Experimental](../document-status.md) -This document highlights compatibility considerations when interacting with AWS managed services. +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 using an aws-sdk, an AWS service-supported propagation format MUST be used to add -context propagation to HTTP headers on the outgoing request, unless another propagator is explicitly provided, -in which case the provided propagator MUST be used. +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: @@ -16,11 +22,11 @@ The following formats are currently natively supported by AWS services for propa * [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. +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. +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. From b7f62c6faf35fd19667f293020294c883e6e29bf Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 19 Apr 2023 16:11:28 -0400 Subject: [PATCH 11/15] Changes requested by the TC --- .../instrumentation/aws-lambda.md | 4 ++-- .../instrumentation/aws-sdk.md | 2 +- .../compatibility/aws.md | 16 +++++++--------- 3 files changed, 10 insertions(+), 12 deletions(-) rename {specification => supplementary-guidelines}/compatibility/aws.md (70%) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 046307355f0..c55447339aa 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -109,7 +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. +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`. @@ -123,7 +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. +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 31ae785ad98..ba179651fbe 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md @@ -11,7 +11,7 @@ Some descriptions are also provided for populating general OpenTelemetry semanti ## Context Propagation -See [compatibility](../../../compatibility/aws.md#context-propagation). +See [compatibility](../../../../supplementary-guidelines/compatibility/aws.md#context-propagation). ## Common Attributes diff --git a/specification/compatibility/aws.md b/supplementary-guidelines/compatibility/aws.md similarity index 70% rename from specification/compatibility/aws.md rename to supplementary-guidelines/compatibility/aws.md index afe76eb060d..f072bb5e123 100644 --- a/specification/compatibility/aws.md +++ b/supplementary-guidelines/compatibility/aws.md @@ -1,21 +1,19 @@ # 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 +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. +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. +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: @@ -24,9 +22,9 @@ The following formats are currently natively supported by AWS services for propa 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) +(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.) -Additional propagation formats MAY be applied to individual request types that support arbitrary attributes such as `SqsMessage`. +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. +Documentation should advise that doing so is subject to attribute limits and billing impacts. From fcdc55debbf49db82b6a4c3279cb24e990500c08 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 3 May 2023 11:02:10 -0400 Subject: [PATCH 12/15] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christian Neumüller --- supplementary-guidelines/compatibility/aws.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/supplementary-guidelines/compatibility/aws.md b/supplementary-guidelines/compatibility/aws.md index f072bb5e123..2575bb568bd 100644 --- a/supplementary-guidelines/compatibility/aws.md +++ b/supplementary-guidelines/compatibility/aws.md @@ -1,19 +1,29 @@ # Compatibility Considerations for AWS -This document highlights compatibility considerations when interacting with 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 outgoing calls to AWS managed services using an aws-sdk, a third-party +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 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. +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. +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: @@ -24,7 +34,3 @@ 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.) - -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. From 2238fa66e1d1697ccf5e794f5d971bc7e657a82c Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 3 May 2023 11:03:01 -0400 Subject: [PATCH 13/15] Apply suggestions from code review Co-authored-by: Anthony Mirabella --- CHANGELOG.md | 2 +- supplementary-guidelines/compatibility/aws.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 479b6b8e816..8a6c928eadd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -111,7 +111,7 @@ 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. +- Add recommendation to use service-supported propagation formats 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)) diff --git a/supplementary-guidelines/compatibility/aws.md b/supplementary-guidelines/compatibility/aws.md index 2575bb568bd..1bc8f449b73 100644 --- a/supplementary-guidelines/compatibility/aws.md +++ b/supplementary-guidelines/compatibility/aws.md @@ -6,9 +6,9 @@ managed services using an aws-sdk, a third-party library, or a direct HTTP reque ## 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 must +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 (AWS Lambda) indirectly triggered by such call. +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 From 370a70a333c53102cac5bef04d29997b180111fd Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 3 May 2023 11:15:01 -0400 Subject: [PATCH 14/15] Fix spacing/line breaks --- supplementary-guidelines/compatibility/aws.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/supplementary-guidelines/compatibility/aws.md b/supplementary-guidelines/compatibility/aws.md index 1bc8f449b73..c5091435d88 100644 --- a/supplementary-guidelines/compatibility/aws.md +++ b/supplementary-guidelines/compatibility/aws.md @@ -1,7 +1,8 @@ # 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. +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 @@ -20,10 +21,15 @@ 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. +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). +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: From 6df04a483721d6746c840fa07f776dbc1ed0f234 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 3 May 2023 12:01:38 -0400 Subject: [PATCH 15/15] Fix changelog --- CHANGELOG.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d48fdf8f72c..93c9a25f2d6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -50,6 +50,11 @@ release. ### Compatibility +### Supplemenatary Guidelines + +- Add guidance to use service-supported propagation formats as default for AWS SDK client calls. + ([#3212](https://github.com/open-telemetry/opentelemetry-specification/pull/3212)) + ### OpenTelemetry Protocol ### SDK Configuration @@ -123,8 +128,6 @@ 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 recommendation to use service-supported propagation formats 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