From a970192cae992e7a74f185cda20fd9f82577db98 Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Tue, 16 Feb 2021 16:04:29 +0900 Subject: [PATCH 01/19] Add semantic conventions for instrumenting AWS Lambda. --- .../trace/instrumentation/aws-lambda.yaml | 61 ++++++++++ .../instrumentation/aws-lambda.md | 104 ++++++++++++++++++ 2 files changed, 165 insertions(+) create mode 100644 semantic_conventions/trace/instrumentation/aws-lambda.yaml create mode 100644 specification/trace/semantic_conventions/instrumentation/aws-lambda.md diff --git a/semantic_conventions/trace/instrumentation/aws-lambda.yaml b/semantic_conventions/trace/instrumentation/aws-lambda.yaml new file mode 100644 index 00000000000..eb1cf33428c --- /dev/null +++ b/semantic_conventions/trace/instrumentation/aws-lambda.yaml @@ -0,0 +1,61 @@ +groups: + - id: aws.lambda + brief: "Lambda function invocation spans." + attributes: + - ref: faas.execution + brief: "The value of the AWS Request ID from the Lambda `Context`." + examples: + - 943ad105-7543-11e6-a9ac-65e093327849 + - ref: faas.id + brief: "The value of the invocation arn for the function from the Lambda `Context`." + examples: + - arn:aws:lambda:us-east-2:123456789012:function:my-function:1 + - ref: cloud.account.id + brief: "The account ID for the function. If not provided on Lambda `Context`, it SHOULD be parsed from the value of `faas.id` as the fifth item when splitting on `:`." + - id: aws.lambda.api-gateway-proxy + brief: > + These conventions apply to AWS Lambda requests that are served by the API Gateway in proxy mode. All the + information about the underlying HTTP request is available. + attributes: + - ref: faas.trigger + brief: "MUST be `http`." + examples: + - http + - ref: http.method + - ref: http.status_code + - ref: http.url + - ref: http.user_agent + - id: aws.lambda.sqs-event + brief: "These conventions apply to an SQS event." + attributes: + - ref: faas.trigger + brief: "MUST be `pubsub`." + examples: + - pubsub + - ref: messaging.system + brief: "MUST be `AmazonSQS`." + examples: + - AmazonSQS + - ref: messaging.operation + brief: "MUST be `process`." + examples: + - process + - id: aws.lambda.sqs-message + brief: "These conventions apply to an SQS message." + attributes: + - ref: faas.trigger + brief: "MUST be `pubsub`." + examples: + - pubsub + - ref: messaging.system + brief: "MUST be `AmazonSQS`." + examples: + - AmazonSQS + - ref: messaging.operation + brief: "MUST be `process`." + examples: + - process + - ref: messaging.message_id + brief: "The value of the message ID for the message." + - ref: messaging.destination + brief: "The value of the event source for the message." diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md new file mode 100644 index 00000000000..e1338afc107 --- /dev/null +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -0,0 +1,104 @@ +# Instrumenting AWS Lambda + +**Status**: [Experimental](../../document-status.md) + +This document defines how to fill semantic conventions when instrumenting an AWS Lambda request handler. AWS +Lambda largely follows the conventions for [FaaS](../faas.md) while [HTTP](../http.md) conventions are also +applicable when handlers are for HTTP requests. + +There are a variety of triggers for Lambda functions, and this document will grow over time to cover all the +use cases. + +## All triggers + +For all events, a span with kind `SERVER` MUST be created corresponding to the function invocation. Unless +stated otherwise below, the name of the span MUST be set to the function name from the Lambda `Context`. + + +| Attribute | Type | Description | Examples | Required | +|---|---|---|---|---| +| [`cloud.account.id`](../../../resource/semantic_conventions/cloud.md) | string | The account ID for the function. If not provided on Lambda `Context`, it SHOULD be parsed from the value of `faas.id` as the fifth item when splitting on `:`. | `opentelemetry` | No | +| [`faas.execution`](../faas.md) | string | The value of the AWS Request ID from the Lambda `Context`. | `943ad105-7543-11e6-a9ac-65e093327849` | No | +| [`faas.id`](../../../resource/semantic_conventions/faas.md) | string | The value of the invocation arn for the function from the Lambda `Context`. [1] | `arn:aws:lambda:us-east-2:123456789012:function:my-function:1` | No | + +**[1]:** For example, in AWS Lambda this field corresponds to the [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) value, in GCP to the URI of the resource, and in Azure to the [FunctionDirectory](https://github.com/Azure/azure-functions-host/wiki/Retrieving-information-about-the-currently-running-function) field. + + +The parent of the span MUST be determined by considering both the environment and any headers or attributes +available from the event. + +If the `_X_AMZN_TRACE_ID` environment variable is set, it SHOULD be parsed into an OpenTelemetry `Context` using +the [AWS X-Ray Propagator](../../../context/api-propagators.md). If the resulting `Context` is sampled, then this +`Context` is the parent of the function span. The environment variable will be set and the `Context` will be +sampled only if AWS X-Ray has been enabled for the Lambda function. A user can disable AWS X-Ray for the function +if this propagation is not desired. + +Otherwise, for an API Gateway Proxy Request, the user's configured propagators should be applied to the HTTP +headers of the request to extract a `Context`. + +## API Gateway + +API Gateway allows a user to trigger a Lambda function in response to HTTP requests. It can be configured to be +a pure proxy, where the information about the original HTTP request is passed to the Lambda function, or as a +configuration for a REST API, in which case only a deserialized body payload is available. In the case the API +gateway is configured to proxy to the Lambda function, the instrumented request handler will have access to all +the information about the HTTP request in the form of an API Gateway Proxy Request Event. + +The Lambda span name SHOULD be set to the `Resource` from the proxy request event, which corresponds to the user +configured HTTP route instead of the function name. + + +| Attribute | Type | Description | Examples | Required | +|---|---|---|---|---| +| [`faas.trigger`](../faas.md) | string | MUST be `http`. | `http` | No | +| [`http.method`](../http.md) | string | HTTP request method. | `GET`; `POST`; `HEAD` | No | +| [`http.status_code`](../http.md) | number | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | No | +| [`http.url`](../http.md) | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | No | +| [`http.user_agent`](../http.md) | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | No | + + +## SQS + +SQS is a message queue that triggers a Lambda function with a batch of messages. In addition to the span for the +function invocation, two spans SHOULD be generated, one for the batch of messages, called an SQS event, and one +for each individual message, called an SQS message. + +The span kind for both spans MUST be `CONSUMER`. + +For the SQS event span, if all the messages in the event have the same event source, the name of the span MUST +be ` process`. If there are multiple sources in the batch, the name MUST be +`multiple_sources `. The parent MUST be the `SERVER` span corresponding to the function invocation. + +For every message in the event, the message's system attributes (not message attributes, which are provided by +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. + + +| Attribute | Type | Description | Examples | Required | +|---|---|---|---|---| +| [`faas.trigger`](../faas.md) | string | MUST be `pubsub`. | `pubsub` | No | +| [`messaging.operation`](../messaging.md) | string | MUST be `process`. | `process` | No | +| [`messaging.system`](../messaging.md) | string | MUST be `AmazonSQS`. | `AmazonSQS` | No | + + +For the SQS message span, the name MUST be ` process`. The parent MUST be the `CONSUMER` span +corresponding to the SQS event. The message's system attributes (not message attributes, which are provided by +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. + + +| Attribute | Type | Description | Examples | Required | +|---|---|---|---|---| +| [`faas.trigger`](../faas.md) | string | MUST be `pubsub`. | `pubsub` | No | +| [`messaging.destination`](../messaging.md) | string | The value of the event source for the message. | `MyQueue`; `MyTopic` | No | +| [`messaging.message_id`](../messaging.md) | string | The value of the message ID for the message. | `452a7c7c7c7048c2f887f61572b18fc2` | No | +| [`messaging.operation`](../messaging.md) | string | MUST be `process`. | `process` | No | +| [`messaging.system`](../messaging.md) | string | MUST be `AmazonSQS`. | `AmazonSQS` | No | + + +Note that `AWSTraceHeader` is the only supported mechanism for propagating `Context` for SQS to prevent conflicts +with other sources. Notably, message attributes (user-provided, not system) are not supported - the linked contexts +are always expected to have been sent as HTTP headers of the `SQS.SendMessage` request that the message originated +from. This is a function of AWS SDK instrumentation, not Lambda instrumentation. From 9a3e3921dc609baf40e68437050152b2cfbdcf7c Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Tue, 16 Feb 2021 16:11:45 +0900 Subject: [PATCH 02/19] Fix link --- .../trace/semantic_conventions/instrumentation/aws-lambda.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index e1338afc107..2ef8716c2fc 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -1,6 +1,6 @@ # Instrumenting AWS Lambda -**Status**: [Experimental](../../document-status.md) +**Status**: [Experimental](../../../document-status.md) This document defines how to fill semantic conventions when instrumenting an AWS Lambda request handler. AWS Lambda largely follows the conventions for [FaaS](../faas.md) while [HTTP](../http.md) conventions are also From 86586ba079de924398b63163940f66361ffa02f5 Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Wed, 17 Feb 2021 12:16:44 +0900 Subject: [PATCH 03/19] Update semantic_conventions/trace/instrumentation/aws-lambda.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christian Neumüller --- semantic_conventions/trace/instrumentation/aws-lambda.yaml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/semantic_conventions/trace/instrumentation/aws-lambda.yaml b/semantic_conventions/trace/instrumentation/aws-lambda.yaml index eb1cf33428c..4c86e846257 100644 --- a/semantic_conventions/trace/instrumentation/aws-lambda.yaml +++ b/semantic_conventions/trace/instrumentation/aws-lambda.yaml @@ -11,7 +11,10 @@ groups: examples: - arn:aws:lambda:us-east-2:123456789012:function:my-function:1 - ref: cloud.account.id - brief: "The account ID for the function. If not provided on Lambda `Context`, it SHOULD be parsed from the value of `faas.id` as the fifth item when splitting on `:`." + brief: "The account ID for the function." + note: > + If not provided on Lambda `Context`, it SHOULD be parsed from the + value of `faas.id` as the fifth item when splitting on `:`. - id: aws.lambda.api-gateway-proxy brief: > These conventions apply to AWS Lambda requests that are served by the API Gateway in proxy mode. All the From a11446fcf38598e8bbfcc9fdd536e8b3f483e12c Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Wed, 17 Feb 2021 12:22:14 +0900 Subject: [PATCH 04/19] Fixes --- .../trace/instrumentation/aws-lambda.yaml | 13 ++++++++--- .../instrumentation/aws-lambda.md | 23 +++++++++++-------- 2 files changed, 23 insertions(+), 13 deletions(-) diff --git a/semantic_conventions/trace/instrumentation/aws-lambda.yaml b/semantic_conventions/trace/instrumentation/aws-lambda.yaml index 4c86e846257..7359a7746d7 100644 --- a/semantic_conventions/trace/instrumentation/aws-lambda.yaml +++ b/semantic_conventions/trace/instrumentation/aws-lambda.yaml @@ -15,24 +15,30 @@ groups: note: > If not provided on Lambda `Context`, it SHOULD be parsed from the value of `faas.id` as the fifth item when splitting on `:`. - - id: aws.lambda.api-gateway-proxy + examples: + - "123456789012" + - id: aws.lambda.api_gateway_proxy brief: > These conventions apply to AWS Lambda requests that are served by the API Gateway in proxy mode. All the information about the underlying HTTP request is available. attributes: - ref: faas.trigger brief: "MUST be `http`." + required: always examples: - http - ref: http.method - ref: http.status_code - ref: http.url - ref: http.user_agent - - id: aws.lambda.sqs-event + - ref: http.route + brief: "The `Resource` from the proxy request event." + - id: aws.lambda.sqs_event brief: "These conventions apply to an SQS event." attributes: - ref: faas.trigger brief: "MUST be `pubsub`." + required: always examples: - pubsub - ref: messaging.system @@ -43,11 +49,12 @@ groups: brief: "MUST be `process`." examples: - process - - id: aws.lambda.sqs-message + - id: aws.lambda.sqs_message brief: "These conventions apply to an SQS message." attributes: - ref: faas.trigger brief: "MUST be `pubsub`." + required: always examples: - pubsub - ref: messaging.system diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 2ef8716c2fc..d5d2f3302bc 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -2,7 +2,7 @@ **Status**: [Experimental](../../../document-status.md) -This document defines how to fill semantic conventions when instrumenting an AWS Lambda request handler. AWS +This document defines how to apply semantic conventions when instrumenting an AWS Lambda request handler. AWS Lambda largely follows the conventions for [FaaS](../faas.md) while [HTTP](../http.md) conventions are also applicable when handlers are for HTTP requests. @@ -17,11 +17,13 @@ stated otherwise below, the name of the span MUST be set to the function name fr | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| -| [`cloud.account.id`](../../../resource/semantic_conventions/cloud.md) | string | The account ID for the function. If not provided on Lambda `Context`, it SHOULD be parsed from the value of `faas.id` as the fifth item when splitting on `:`. | `opentelemetry` | No | +| [`cloud.account.id`](../../../resource/semantic_conventions/cloud.md) | string | The account ID for the function. [1] | `123456789012` | No | | [`faas.execution`](../faas.md) | string | The value of the AWS Request ID from the Lambda `Context`. | `943ad105-7543-11e6-a9ac-65e093327849` | No | -| [`faas.id`](../../../resource/semantic_conventions/faas.md) | string | The value of the invocation arn for the function from the Lambda `Context`. [1] | `arn:aws:lambda:us-east-2:123456789012:function:my-function:1` | No | +| [`faas.id`](../../../resource/semantic_conventions/faas.md) | string | The value of the invocation arn for the function from the Lambda `Context`. [2] | `arn:aws:lambda:us-east-2:123456789012:function:my-function:1` | No | -**[1]:** For example, in AWS Lambda this field corresponds to the [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) value, in GCP to the URI of the resource, and in Azure to the [FunctionDirectory](https://github.com/Azure/azure-functions-host/wiki/Retrieving-information-about-the-currently-running-function) field. +**[1]:** If not provided on Lambda `Context`, it SHOULD be parsed from the value of `faas.id` as the fifth item when splitting on `:`. + +**[2]:** For example, in AWS Lambda this field corresponds to the [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) value, in GCP to the URI of the resource, and in Azure to the [FunctionDirectory](https://github.com/Azure/azure-functions-host/wiki/Retrieving-information-about-the-currently-running-function) field. The parent of the span MUST be determined by considering both the environment and any headers or attributes @@ -47,11 +49,12 @@ the information about the HTTP request in the form of an API Gateway Proxy Reque The Lambda span name SHOULD be set to the `Resource` from the proxy request event, which corresponds to the user configured HTTP route instead of the function name. - + | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| -| [`faas.trigger`](../faas.md) | string | MUST be `http`. | `http` | No | +| [`faas.trigger`](../faas.md) | string | MUST be `http`. | `http` | Yes | | [`http.method`](../http.md) | string | HTTP request method. | `GET`; `POST`; `HEAD` | No | +| [`http.route`](../http.md) | string | The `Resource` from the proxy request event. | `/users/:userID?` | No | | [`http.status_code`](../http.md) | number | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | No | | [`http.url`](../http.md) | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | No | | [`http.user_agent`](../http.md) | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | No | @@ -74,10 +77,10 @@ the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an O 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. - + | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| -| [`faas.trigger`](../faas.md) | string | MUST be `pubsub`. | `pubsub` | No | +| [`faas.trigger`](../faas.md) | string | MUST be `pubsub`. | `pubsub` | Yes | | [`messaging.operation`](../messaging.md) | string | MUST be `process`. | `process` | No | | [`messaging.system`](../messaging.md) | string | MUST be `AmazonSQS`. | `AmazonSQS` | No | @@ -88,10 +91,10 @@ the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an O 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. - + | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| -| [`faas.trigger`](../faas.md) | string | MUST be `pubsub`. | `pubsub` | No | +| [`faas.trigger`](../faas.md) | string | MUST be `pubsub`. | `pubsub` | Yes | | [`messaging.destination`](../messaging.md) | string | The value of the event source for the message. | `MyQueue`; `MyTopic` | No | | [`messaging.message_id`](../messaging.md) | string | The value of the message ID for the message. | `452a7c7c7c7048c2f887f61572b18fc2` | No | | [`messaging.operation`](../messaging.md) | string | MUST be `process`. | `process` | No | From 438eb4976932a588c54bdbf50219dfb31a93903d Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Mon, 22 Feb 2021 15:38:53 +0900 Subject: [PATCH 05/19] 2 spans --- .../instrumentation/aws-lambda.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index d5d2f3302bc..b88f20f7bf8 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -11,8 +11,9 @@ use cases. ## All triggers -For all events, a span with kind `SERVER` MUST be created corresponding to the function invocation. Unless -stated otherwise below, the name of the span MUST be set to the function name from the Lambda `Context`. +For all events, a span with kind `SERVER` MUST be created corresponding to the function invocation unless stated +otherwise below. Unless stated otherwise below, the name of the span MUST be set to the function name from the +Lambda `Context`. | Attribute | Type | Description | Examples | Required | @@ -62,9 +63,12 @@ configured HTTP route instead of the function name. ## SQS -SQS is a message queue that triggers a Lambda function with a batch of messages. In addition to the span for the -function invocation, two spans SHOULD be generated, one for the batch of messages, called an SQS event, and one -for each individual message, called an SQS message. +SQS is a message queue that triggers a Lambda function with a batch of messages. So we consider processing both +of a batch and of each individual message. The function invocation span MUST correspond to the SQS event, which +is the batch of messages. For each message, an additional span SHOULD be created to correspond with the handling +of the SQS message. Because handling of a message will be inside user business logic, not the Lambda framework, +automatic instrumentation mechanisms without code change will often not be able to be able to instrument the +processing of the individual messages. The span kind for both spans MUST be `CONSUMER`. From 125feac1c66979faa12f19a0c43cdb798bb29644 Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Wed, 3 Mar 2021 18:40:09 +0900 Subject: [PATCH 06/19] Inline MD --- .../trace/instrumentation/aws-lambda.yaml | 71 ------------------- .../instrumentation/aws-lambda.md | 51 ++++--------- 2 files changed, 15 insertions(+), 107 deletions(-) delete mode 100644 semantic_conventions/trace/instrumentation/aws-lambda.yaml diff --git a/semantic_conventions/trace/instrumentation/aws-lambda.yaml b/semantic_conventions/trace/instrumentation/aws-lambda.yaml deleted file mode 100644 index 7359a7746d7..00000000000 --- a/semantic_conventions/trace/instrumentation/aws-lambda.yaml +++ /dev/null @@ -1,71 +0,0 @@ -groups: - - id: aws.lambda - brief: "Lambda function invocation spans." - attributes: - - ref: faas.execution - brief: "The value of the AWS Request ID from the Lambda `Context`." - examples: - - 943ad105-7543-11e6-a9ac-65e093327849 - - ref: faas.id - brief: "The value of the invocation arn for the function from the Lambda `Context`." - examples: - - arn:aws:lambda:us-east-2:123456789012:function:my-function:1 - - ref: cloud.account.id - brief: "The account ID for the function." - note: > - If not provided on Lambda `Context`, it SHOULD be parsed from the - value of `faas.id` as the fifth item when splitting on `:`. - examples: - - "123456789012" - - id: aws.lambda.api_gateway_proxy - brief: > - These conventions apply to AWS Lambda requests that are served by the API Gateway in proxy mode. All the - information about the underlying HTTP request is available. - attributes: - - ref: faas.trigger - brief: "MUST be `http`." - required: always - examples: - - http - - ref: http.method - - ref: http.status_code - - ref: http.url - - ref: http.user_agent - - ref: http.route - brief: "The `Resource` from the proxy request event." - - id: aws.lambda.sqs_event - brief: "These conventions apply to an SQS event." - attributes: - - ref: faas.trigger - brief: "MUST be `pubsub`." - required: always - examples: - - pubsub - - ref: messaging.system - brief: "MUST be `AmazonSQS`." - examples: - - AmazonSQS - - ref: messaging.operation - brief: "MUST be `process`." - examples: - - process - - id: aws.lambda.sqs_message - brief: "These conventions apply to an SQS message." - attributes: - - ref: faas.trigger - brief: "MUST be `pubsub`." - required: always - examples: - - pubsub - - ref: messaging.system - brief: "MUST be `AmazonSQS`." - examples: - - AmazonSQS - - ref: messaging.operation - brief: "MUST be `process`." - examples: - - process - - ref: messaging.message_id - brief: "The value of the message ID for the message." - - ref: messaging.destination - brief: "The value of the event source for the message." diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index b88f20f7bf8..dc5c0be19e7 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -15,17 +15,11 @@ For all events, a span with kind `SERVER` MUST be created corresponding to the f otherwise below. Unless stated otherwise below, the name of the span MUST be set to the function name from the Lambda `Context`. - -| Attribute | Type | Description | Examples | Required | -|---|---|---|---|---| -| [`cloud.account.id`](../../../resource/semantic_conventions/cloud.md) | string | The account ID for the function. [1] | `123456789012` | No | -| [`faas.execution`](../faas.md) | string | The value of the AWS Request ID from the Lambda `Context`. | `943ad105-7543-11e6-a9ac-65e093327849` | No | -| [`faas.id`](../../../resource/semantic_conventions/faas.md) | string | The value of the invocation arn for the function from the Lambda `Context`. [2] | `arn:aws:lambda:us-east-2:123456789012:function:my-function:1` | No | +The following attributes SHOULD be set. -**[1]:** If not provided on Lambda `Context`, it SHOULD be parsed from the value of `faas.id` as the fifth item when splitting on `:`. - -**[2]:** For example, in AWS Lambda this field corresponds to the [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) value, in GCP to the URI of the resource, and in Azure to the [FunctionDirectory](https://github.com/Azure/azure-functions-host/wiki/Retrieving-information-about-the-currently-running-function) field. - +- [`faas.execution`](../faas.md) - This is always available through an accessor on the Lambda `Context` +- [`faas.id`](../../../resource/semantic_conventions/faas.md) - This is always available through an accessor on the Lambda `Context` +- [`cloud.account.id`](../../../resource/semantic_conventions/cloud.md) - In some languages, this is available as an accessor on the Lambda `Context`. Otherwise, it can be parsed from the value of `faas.id` as the fifth item when splitting on `:` The parent of the span MUST be determined by considering both the environment and any headers or attributes available from the event. @@ -50,16 +44,8 @@ the information about the HTTP request in the form of an API Gateway Proxy Reque The Lambda span name SHOULD be set to the `Resource` from the proxy request event, which corresponds to the user configured HTTP route instead of the function name. - -| Attribute | Type | Description | Examples | Required | -|---|---|---|---|---| -| [`faas.trigger`](../faas.md) | string | MUST be `http`. | `http` | Yes | -| [`http.method`](../http.md) | string | HTTP request method. | `GET`; `POST`; `HEAD` | No | -| [`http.route`](../http.md) | string | The `Resource` from the proxy request event. | `/users/:userID?` | No | -| [`http.status_code`](../http.md) | number | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | No | -| [`http.url`](../http.md) | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | No | -| [`http.user_agent`](../http.md) | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | No | - +[`faas.trigger`](../faas.md) MUST be set to `http`. [HTTP attributes](../http.md) SHOULD be set based on the +available information in the proxy request event. ## SQS @@ -81,13 +67,9 @@ the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an O 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. - -| Attribute | Type | Description | Examples | Required | -|---|---|---|---|---| -| [`faas.trigger`](../faas.md) | string | MUST be `pubsub`. | `pubsub` | Yes | -| [`messaging.operation`](../messaging.md) | string | MUST be `process`. | `process` | No | -| [`messaging.system`](../messaging.md) | string | MUST be `AmazonSQS`. | `AmazonSQS` | No | - +[`faas.trigger`](../faas.md) MUST be set to `pubsub`. +[`messaging.operation`](../messaging.md) MUST be set to `process`. +[`messaging.system`](../messaging.md) MUST be set to `AmazonSQS`. For the SQS message span, the name MUST be ` process`. The parent MUST be the `CONSUMER` span corresponding to the SQS event. The message's system attributes (not message attributes, which are provided by @@ -95,15 +77,12 @@ the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an O 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. - -| Attribute | Type | Description | Examples | Required | -|---|---|---|---|---| -| [`faas.trigger`](../faas.md) | string | MUST be `pubsub`. | `pubsub` | Yes | -| [`messaging.destination`](../messaging.md) | string | The value of the event source for the message. | `MyQueue`; `MyTopic` | No | -| [`messaging.message_id`](../messaging.md) | string | The value of the message ID for the message. | `452a7c7c7c7048c2f887f61572b18fc2` | No | -| [`messaging.operation`](../messaging.md) | string | MUST be `process`. | `process` | No | -| [`messaging.system`](../messaging.md) | string | MUST be `AmazonSQS`. | `AmazonSQS` | No | - +[`faas.trigger`](../faas.md) MUST be set to `pubsub`. +[`messaging.operation`](../messaging.md) MUST be set to `process`. +[`messaging.system`](../messaging.md) MUST be set to `AmazonSQS`. + +Other [Messaging attributes](../messaging.md) SHOULD be set based on the available information in the SQS message +event. Note that `AWSTraceHeader` is the only supported mechanism for propagating `Context` for SQS to prevent conflicts with other sources. Notably, message attributes (user-provided, not system) are not supported - the linked contexts From c4105fc495d814e9490e66c0204008b15a88d706 Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Thu, 4 Mar 2021 17:11:59 +0900 Subject: [PATCH 07/19] Cleanups --- .../instrumentation/aws-lambda.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index dc5c0be19e7..3d50cedae89 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -17,10 +17,12 @@ Lambda `Context`. The following attributes SHOULD be set. -- [`faas.execution`](../faas.md) - This is always available through an accessor on the Lambda `Context` -- [`faas.id`](../../../resource/semantic_conventions/faas.md) - This is always available through an accessor on the Lambda `Context` +- [`faas.execution`](../faas.md) - The value of the AWS Request ID, which is always available through an accessor on the Lambda `Context` +- [`faas.id`](../../../resource/semantic_conventions/faas.md) - The value of the invocation arn for the function, which is always available through an accessor on the Lambda `Context` - [`cloud.account.id`](../../../resource/semantic_conventions/cloud.md) - In some languages, this is available as an accessor on the Lambda `Context`. Otherwise, it can be parsed from the value of `faas.id` as the fifth item when splitting on `:` +### Determining the parent of a span + The parent of the span MUST be determined by considering both the environment and any headers or attributes available from the event. @@ -41,8 +43,8 @@ configuration for a REST API, in which case only a deserialized body payload is gateway is configured to proxy to the Lambda function, the instrumented request handler will have access to all the information about the HTTP request in the form of an API Gateway Proxy Request Event. -The Lambda span name SHOULD be set to the `Resource` from the proxy request event, which corresponds to the user -configured HTTP route instead of the function name. +The Lambda span name and the [`http.route` span attribute](../http.md) SHOULD be set to the `Resource` from the +proxy request event, which corresponds to the user configured HTTP route instead of the function name. [`faas.trigger`](../faas.md) MUST be set to `http`. [HTTP attributes](../http.md) SHOULD be set based on the available information in the proxy request event. @@ -53,11 +55,13 @@ SQS is a message queue that triggers a Lambda function with a batch of messages. of a batch and of each individual message. The function invocation span MUST correspond to the SQS event, which is the batch of messages. For each message, an additional span SHOULD be created to correspond with the handling of the SQS message. Because handling of a message will be inside user business logic, not the Lambda framework, -automatic instrumentation mechanisms without code change will often not be able to be able to instrument the -processing of the individual messages. +automatic instrumentation mechanisms without code change will often not be able to instrument the processing of +the individual messages. The span kind for both spans MUST be `CONSUMER`. +### SQS Event + For the SQS event span, if all the messages in the event have the same event source, the name of the span MUST be ` process`. If there are multiple sources in the batch, the name MUST be `multiple_sources `. The parent MUST be the `SERVER` span corresponding to the function invocation. @@ -71,6 +75,8 @@ added as a link to the span. This means the span may have as many links as messa [`messaging.operation`](../messaging.md) MUST be set to `process`. [`messaging.system`](../messaging.md) MUST be set to `AmazonSQS`. +### SQS Message + For the SQS message span, the name MUST be ` process`. The parent MUST be the `CONSUMER` span corresponding to the SQS event. The message's system attributes (not message attributes, which are provided by the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be From bc363eb460de68626615de7c727627940becb23b Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Tue, 16 Mar 2021 11:53:26 +0900 Subject: [PATCH 08/19] Clean --- .../trace/semantic_conventions/instrumentation/aws-lambda.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 3d50cedae89..d6ca63b11c2 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -58,13 +58,13 @@ of the SQS message. Because handling of a message will be inside user business l automatic instrumentation mechanisms without code change will often not be able to instrument the processing of the individual messages. -The span kind for both spans MUST be `CONSUMER`. +The span kind for both types of SQS spans MUST be `CONSUMER`. ### SQS Event For the SQS event span, if all the messages in the event have the same event source, the name of the span MUST be ` process`. If there are multiple sources in the batch, the name MUST be -`multiple_sources `. The parent MUST be the `SERVER` span corresponding to the function invocation. +`multiple_sources process`. The parent MUST be the `SERVER` span corresponding to the function invocation. For every message in the event, the message's system attributes (not message attributes, which are provided by the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be From c2589505b27f6ffa4057d93a21b30a9bbefd3f13 Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Thu, 18 Mar 2021 11:52:41 +0900 Subject: [PATCH 09/19] Cleanups --- semantic_conventions/trace/messaging.yaml | 2 +- .../trace/semantic_conventions/README.md | 3 +- .../instrumentation/aws-lambda.md | 50 ++++++++++++------- .../trace/semantic_conventions/messaging.md | 2 +- 4 files changed, 35 insertions(+), 22 deletions(-) diff --git a/semantic_conventions/trace/messaging.yaml b/semantic_conventions/trace/messaging.yaml index 9a5d42402b1..841e1e65085 100644 --- a/semantic_conventions/trace/messaging.yaml +++ b/semantic_conventions/trace/messaging.yaml @@ -9,7 +9,7 @@ groups: type: string required: always brief: 'A string identifying the messaging system.' - examples: ['kafka', 'rabbitmq', 'activemq'] + examples: ['kafka', 'rabbitmq', 'activemq', 'AmazonSQS'] - id: destination type: string required: always diff --git a/specification/trace/semantic_conventions/README.md b/specification/trace/semantic_conventions/README.md index 4883dd99ce5..1b481f2621b 100644 --- a/specification/trace/semantic_conventions/README.md +++ b/specification/trace/semantic_conventions/README.md @@ -21,7 +21,8 @@ The following semantic conventions for spans are defined: * [RPC/RMI](rpc.md): Spans for remote procedure calls (e.g., gRPC). * [Messaging](messaging.md): Spans for interaction with messaging systems (queues, publish/subscribe, etc.). * [FaaS](faas.md): Spans for Function as a Service (e.g., AWS Lambda). -* [Exceptions](exceptions.md): Attributes for recording exceptions associated with a span + * [AWS Lambda](instrumentation/aws-lambda.md): Details on populating attributes for AWS Lambda. +* [Exceptions](exceptions.md): Attributes for recording exceptions associated with a span. Apart from semantic conventions for traces and [metrics](../../metrics/semantic_conventions/README.md), OpenTelemetry also defines the concept of overarching [Resources](../../resource/sdk.md) with their own diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index d6ca63b11c2..5c5f5fc7ea7 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -15,10 +15,10 @@ For all events, a span with kind `SERVER` MUST be created corresponding to the f otherwise below. Unless stated otherwise below, the name of the span MUST be set to the function name from the Lambda `Context`. -The following attributes SHOULD be set. +The following attributes SHOULD be set: - [`faas.execution`](../faas.md) - The value of the AWS Request ID, which is always available through an accessor on the Lambda `Context` -- [`faas.id`](../../../resource/semantic_conventions/faas.md) - The value of the invocation arn for the function, which is always available through an accessor on the Lambda `Context` +- [`faas.id`](../../../resource/semantic_conventions/faas.md) - The value of the invocation ARN for the function, which is always available through an accessor on the Lambda `Context` - [`cloud.account.id`](../../../resource/semantic_conventions/cloud.md) - In some languages, this is available as an accessor on the Lambda `Context`. Otherwise, it can be parsed from the value of `faas.id` as the fifth item when splitting on `:` ### Determining the parent of a span @@ -43,20 +43,23 @@ configuration for a REST API, in which case only a deserialized body payload is gateway is configured to proxy to the Lambda function, the instrumented request handler will have access to all the information about the HTTP request in the form of an API Gateway Proxy Request Event. -The Lambda span name and the [`http.route` span attribute](../http.md) SHOULD be set to the `Resource` from the -proxy request event, which corresponds to the user configured HTTP route instead of the function name. +The Lambda span name and the [`http.route` span attribute](../http.md#http-server-semantic-conventions) SHOULD +be set to the [resource property][] from the proxy request event, which corresponds to the user configured HTTP +route instead of the function name. [`faas.trigger`](../faas.md) MUST be set to `http`. [HTTP attributes](../http.md) SHOULD be set based on the available information in the proxy request event. +[resource property]: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format + ## SQS -SQS is a message queue that triggers a Lambda function with a batch of messages. So we consider processing both -of a batch and of each individual message. The function invocation span MUST correspond to the SQS event, which -is the batch of messages. For each message, an additional span SHOULD be created to correspond with the handling -of the SQS message. Because handling of a message will be inside user business logic, not the Lambda framework, -automatic instrumentation mechanisms without code change will often not be able to instrument the processing of -the individual messages. +Amazon Simple Queue Service (SQS) is a message queue that triggers a Lambda function with a batch of messages. +So we consider processing both of a batch and of each individual message. The function invocation span MUST +correspond to the SQS event, which is the batch of messages. For each message, an additional span SHOULD be +created to correspond with the handling of the SQS message. Because handling of a message will be inside user +business logic, not the Lambda framework, automatic instrumentation mechanisms without code change will often +not be able to instrument the processing of the individual messages. The span kind for both types of SQS spans MUST be `CONSUMER`. @@ -66,7 +69,7 @@ For the SQS event span, if all the messages in the event have the same event sou be ` process`. If there are multiple sources in the batch, the name MUST be `multiple_sources process`. The parent MUST be the `SERVER` span corresponding to the function invocation. -For every message in the event, the message's system attributes (not message attributes, which are provided by +For every message in the event, the [message system attributes][] (not message attributes, which are provided by 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. @@ -74,23 +77,32 @@ added as a link to the span. This means the span may have as many links as messa [`faas.trigger`](../faas.md) MUST be set to `pubsub`. [`messaging.operation`](../messaging.md) MUST be set to `process`. [`messaging.system`](../messaging.md) MUST be set to `AmazonSQS`. +[`messaging.destination`](../messaging.md#messaging-attributes) MUST be set to `queue`. ### SQS Message For the SQS message span, the name MUST be ` process`. The parent MUST be the `CONSUMER` span -corresponding to the SQS event. The message's system attributes (not message attributes, which are provided by +corresponding to the SQS event. The [message system attributes][] (not message attributes, which are provided by 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. [`faas.trigger`](../faas.md) MUST be set to `pubsub`. -[`messaging.operation`](../messaging.md) MUST be set to `process`. -[`messaging.system`](../messaging.md) MUST be set to `AmazonSQS`. +[`messaging.operation`](../messaging.md#messaging-attributes) MUST be set to `process`. +[`messaging.system`](../messaging.md#messaging-attributes) MUST be set to `AmazonSQS`. +[`messaging.destination`](../messaging.md#messaging-attributes) MUST be set to `queue`. -Other [Messaging attributes](../messaging.md) SHOULD be set based on the available information in the SQS message +Other [Messaging attributes](../messaging.md#messaging-attributes) SHOULD be set based on the available information in the SQS message event. -Note that `AWSTraceHeader` is the only supported mechanism for propagating `Context` for SQS to prevent conflicts -with other sources. Notably, message attributes (user-provided, not system) are not supported - the linked contexts -are always expected to have been sent as HTTP headers of the `SQS.SendMessage` request that the message originated -from. This is a function of AWS SDK instrumentation, not Lambda instrumentation. +Note that `AWSTraceHeader` is the only supported mechanism for propagating `Context` in instrumentation for SQS +to prevent conflicts with other sources. Notably, message attributes (user-provided, not system) are not supported - +the linked contexts are always expected to have been sent as HTTP headers of the `SQS.SendMessage` request that +the message originated from. This is a function of AWS SDK instrumentation, not Lambda instrumentation. + +Using the `AWSTraceHeader` ensures that propagation will work across AWS services that may be integrated to +Lambda via SQS, for example a flow that goes through S3 -> SNS -> SQS -> Lambda. `AWSTraceHeader` is only a means +of propagating context and not tied to any particular observability backend. Notably, using it does not imply +using AWS X-Ray - any observability backend will fully function using this propagation mechanism. + +[message system attributes]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-message-metadata.html#sqs-message-system-attributes diff --git a/specification/trace/semantic_conventions/messaging.md b/specification/trace/semantic_conventions/messaging.md index efb939278a8..1c3a96dbf9c 100644 --- a/specification/trace/semantic_conventions/messaging.md +++ b/specification/trace/semantic_conventions/messaging.md @@ -127,7 +127,7 @@ The following operations related to messages are defined for these semantic conv | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| -| `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `activemq` | Yes | +| `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `activemq`; `AmazonSQS` | Yes | | `messaging.destination` | string | The message destination name. This might be equal to the span name but is required nevertheless. | `MyQueue`; `MyTopic` | Yes | | `messaging.destination_kind` | string | The kind of message destination | `queue` | Conditional [1] | | `messaging.temp_destination` | boolean | A boolean that is true if the message destination is temporary. | | If missing, it is assumed to be false. | From 2869623a598cfd4c70b5ce36f679370145f6caaf Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Thu, 18 Mar 2021 13:47:22 +0900 Subject: [PATCH 10/19] Examples --- .../instrumentation/aws-lambda.md | 90 ++++++++++++++++++- 1 file changed, 86 insertions(+), 4 deletions(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 5c5f5fc7ea7..9e97b2baf15 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -48,9 +48,11 @@ be set to the [resource property][] from the proxy request event, which correspo route instead of the function name. [`faas.trigger`](../faas.md) MUST be set to `http`. [HTTP attributes](../http.md) SHOULD be set based on the -available information in the proxy request event. +available information in the proxy request event. `http.scheme` is available as the `x-forwarded-proto` header +in the proxy request. Refer to the [input format][] for more details. [resource property]: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format +[input format]: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format ## SQS @@ -59,7 +61,8 @@ So we consider processing both of a batch and of each individual message. The fu correspond to the SQS event, which is the batch of messages. For each message, an additional span SHOULD be created to correspond with the handling of the SQS message. Because handling of a message will be inside user business logic, not the Lambda framework, automatic instrumentation mechanisms without code change will often -not be able to instrument the processing of the individual messages. +not be able to instrument the processing of the individual messages. Instrumentation SHOULD provide utilities +for creating message processing spans within user code. The span kind for both types of SQS spans MUST be `CONSUMER`. @@ -77,7 +80,7 @@ added as a link to the span. This means the span may have as many links as messa [`faas.trigger`](../faas.md) MUST be set to `pubsub`. [`messaging.operation`](../messaging.md) MUST be set to `process`. [`messaging.system`](../messaging.md) MUST be set to `AmazonSQS`. -[`messaging.destination`](../messaging.md#messaging-attributes) MUST be set to `queue`. +[`messaging.destination_kind`](../messaging.md#messaging-attributes) MUST be set to `queue`. ### SQS Message @@ -90,7 +93,7 @@ added as a link to the span. [`faas.trigger`](../faas.md) MUST be set to `pubsub`. [`messaging.operation`](../messaging.md#messaging-attributes) MUST be set to `process`. [`messaging.system`](../messaging.md#messaging-attributes) MUST be set to `AmazonSQS`. -[`messaging.destination`](../messaging.md#messaging-attributes) MUST be set to `queue`. +[`messaging.destination_kind`](../messaging.md#messaging-attributes) MUST be set to `queue`. Other [Messaging attributes](../messaging.md#messaging-attributes) SHOULD be set based on the available information in the SQS message event. @@ -106,3 +109,82 @@ of propagating context and not tied to any particular observability backend. Not using AWS X-Ray - any observability backend will fully function using this propagation mechanism. [message system attributes]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-message-metadata.html#sqs-message-system-attributes + +## Examples + +### API Gateway Request Proxy (Lambda tracing passive) + +Given a process C that sends an HTTP request to an API Gateway endpoint with path `/pets/{petId}` configured for +a Lambda function F: + +``` +Process C: | Span Client | +-- +Process F: | Span Function ! +``` + +| Field or Attribute | `Span Client` | `Span Function` | +|-|-|-| +| Span name | `HTTP GET` | `/pets/{petId}` | +| Parent | | Span Client | +| SpanKind | `CLIENT` | `SERVER` | +| Status | `Ok` | `Ok` | +| `faas.execution` | | `79104EXAMPLEB723` | +| `faas.id` | | `arn:aws:lambda:us-west-2:123456789012:function:my-function.` | +| `faas.trigger` | | `http` | +| `cloud.account.id` | | `12345678912` | +| `net.peer.name` | `foo.execute-api.us-east-1.amazonaws.com` | | +| `net.peer.port` | `413` | | +| `http.method` | `GET` | `GET` | +| `http.user_agent` | `okhttp 3.0` | `okhttp 3.0` | +| `http.url` | `https://foo.execute-api.us-east-1.amazonaws.com/pets/10` | | +| `http.scheme` | | `https` | +| `http.host` | | `foo.execute-api.us-east-1.amazonaws.com` | +| `http.target` | | `/pets/10` | +| `http.route` | | `/pets/{petId}` | +| `http.status_code` | `200` | `200` | + +### API Gateway Request Proxy (Lambda tracing active) + +Active tracing in Lambda means an API Gateway span `Span APIGW` and a Lambda runtime invocation span `Span Lambda` +will be exported to AWS X-Ray. All attributes above are the same except that in this case, the parent of `APIGW` +is `Span Client` and the parent of `Span Function` is `Span Lambda`. + +### SQS (Lambda tracing passive) + +Given a process P, that sends two messages to a queue Q on SQS, and a Lambda function F, which processes both of them in one batch (Span ProcBatch) and +generates a processing span for each message separately (Spans Proc1 and Proc2). + + + +``` +Process P: | Span Prod1 | Span Prod2 | +-- +Function F: | Span ProcBatch | + | Span Proc1 | + | Span Proc2 | +``` + +| Field or Attribute | Span Prod1 | Span Prod2 | Span ProcBatch | Span Proc1 | Span Proc2 | +|-|-|-|-|-|-| +| Span name | `Q send` | `Q send` | `Q process` | `Q process` | `Q process` | +| Parent | | | | Span ProcBatch | Span ProcBatch | +| Links | | | | Span Prod1 | Span Prod2 | +| SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` | `CONSUMER` | `CONSUMER` | +| Status | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` | +| `messaging.system` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | +| `messaging.destination` | `Q` | `Q` | | `Q` | `Q` | +| `messaging.destination_kind` | `queue` | `queue` | `queue` | `queue` | `queue` | +| `messaging.operation` | | | `process` | `process"` | `process` | +| `messaging.message_id` | | | | `"a1"` | `"a2"` | + +The above requires user code change to create `Span Proc1` and `Span Proc2` - if Java, they would inherit from +[TracingSqsMessageHandler][] instead of Lambda's standard `RequestHandler` to enable them. Otherwise they would +not exist. + +[TracingSqsMessageHandler]: https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/aws-lambda-1.0/library/src/main/java/io/opentelemetry/instrumentation/awslambda/v1_0/TracingSqsMessageHandler.java + +### SQS (Lambda tracing active) + +Active tracing in Lambda means a Lambda runtime invocation span `Span Lambda` will be exported to X-Ray. In this +case, all of the above is the same except `Span ProcBatch` will have a parent of `Span Lambda`. From 11b0a9f7ada13cff3a9390f4e78c02fc61a8a255 Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Thu, 18 Mar 2021 13:48:21 +0900 Subject: [PATCH 11/19] Consistency --- .../trace/semantic_conventions/instrumentation/aws-lambda.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 9e97b2baf15..4b475c703bc 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -120,7 +120,7 @@ a Lambda function F: ``` Process C: | Span Client | -- -Process F: | Span Function ! +Function F: | Span Function | ``` | Field or Attribute | `Span Client` | `Span Function` | From 812ef2e10f3c66de5b6e33884cad7b957090f23e Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Thu, 18 Mar 2021 13:49:02 +0900 Subject: [PATCH 12/19] Typo --- .../trace/semantic_conventions/instrumentation/aws-lambda.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 4b475c703bc..76aaf658096 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -130,7 +130,7 @@ Function F: | Span Function | | SpanKind | `CLIENT` | `SERVER` | | Status | `Ok` | `Ok` | | `faas.execution` | | `79104EXAMPLEB723` | -| `faas.id` | | `arn:aws:lambda:us-west-2:123456789012:function:my-function.` | +| `faas.id` | | `arn:aws:lambda:us-west-2:123456789012:function:my-function` | | `faas.trigger` | | `http` | | `cloud.account.id` | | `12345678912` | | `net.peer.name` | `foo.execute-api.us-east-1.amazonaws.com` | | From 1065bb598f7de1295c4913c4aaabf71ef485a211 Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Thu, 18 Mar 2021 13:50:05 +0900 Subject: [PATCH 13/19] Readability --- .../trace/semantic_conventions/instrumentation/aws-lambda.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 76aaf658096..4f6df201969 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -178,8 +178,8 @@ Function F: | Span ProcBatch | | `messaging.operation` | | | `process` | `process"` | `process` | | `messaging.message_id` | | | | `"a1"` | `"a2"` | -The above requires user code change to create `Span Proc1` and `Span Proc2` - if Java, they would inherit from -[TracingSqsMessageHandler][] instead of Lambda's standard `RequestHandler` to enable them. Otherwise they would +The above requires user code change to create `Span Proc1` and `Span Proc2` - in Java, the user would inherit from +[TracingSqsMessageHandler][] instead of Lambda's standard `RequestHandler` to enable them. Otherwise the spans would not exist. [TracingSqsMessageHandler]: https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/aws-lambda-1.0/library/src/main/java/io/opentelemetry/instrumentation/awslambda/v1_0/TracingSqsMessageHandler.java From fc3f70781717238861d35003f08ee1f9c9e14ca9 Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Thu, 18 Mar 2021 13:52:19 +0900 Subject: [PATCH 14/19] Formatting --- .../instrumentation/aws-lambda.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 4f6df201969..4c341a6577d 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -77,10 +77,10 @@ the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an O 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. -[`faas.trigger`](../faas.md) MUST be set to `pubsub`. -[`messaging.operation`](../messaging.md) MUST be set to `process`. -[`messaging.system`](../messaging.md) MUST be set to `AmazonSQS`. -[`messaging.destination_kind`](../messaging.md#messaging-attributes) MUST be set to `queue`. +- [`faas.trigger`](../faas.md) MUST be set to `pubsub`. +- [`messaging.operation`](../messaging.md) MUST be set to `process`. +- [`messaging.system`](../messaging.md) MUST be set to `AmazonSQS`. +- [`messaging.destination_kind`](../messaging.md#messaging-attributes) MUST be set to `queue`. ### SQS Message @@ -90,10 +90,10 @@ the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an O 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. -[`faas.trigger`](../faas.md) MUST be set to `pubsub`. -[`messaging.operation`](../messaging.md#messaging-attributes) MUST be set to `process`. -[`messaging.system`](../messaging.md#messaging-attributes) MUST be set to `AmazonSQS`. -[`messaging.destination_kind`](../messaging.md#messaging-attributes) MUST be set to `queue`. +- [`faas.trigger`](../faas.md) MUST be set to `pubsub`. +- [`messaging.operation`](../messaging.md#messaging-attributes) MUST be set to `process`. +- [`messaging.system`](../messaging.md#messaging-attributes) MUST be set to `AmazonSQS`. +- [`messaging.destination_kind`](../messaging.md#messaging-attributes) MUST be set to `queue`. Other [Messaging attributes](../messaging.md#messaging-attributes) SHOULD be set based on the available information in the SQS message event. @@ -155,8 +155,6 @@ is `Span Client` and the parent of `Span Function` is `Span Lambda`. Given a process P, that sends two messages to a queue Q on SQS, and a Lambda function F, which processes both of them in one batch (Span ProcBatch) and generates a processing span for each message separately (Spans Proc1 and Proc2). - - ``` Process P: | Span Prod1 | Span Prod2 | -- From eef19acf080687ae3b99bfb5af3cb202901138ec Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Thu, 18 Mar 2021 13:53:44 +0900 Subject: [PATCH 15/19] Changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 581642fdd0c..0e0898d4caa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,8 @@ release. ### Semantic Conventions +- Add details for filling semantic conventiosn for AWS Lambda ([#1442](https://github.com/open-telemetry/opentelemetry-specification/pull/1442)) + ### Compatibility - Add initial OpenTracing compatibility section. From 5c9d5750a68b550bcbb0f8b13fd81f21fa7b3e61 Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Sat, 20 Mar 2021 12:45:07 +0900 Subject: [PATCH 16/19] Apply suggestions from code review Co-authored-by: Armin Ruech --- CHANGELOG.md | 2 +- .../instrumentation/aws-lambda.md | 14 ++++++++++---- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 06b81b97769..d23b99f5efb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,7 +26,7 @@ release. ### Semantic Conventions -- Add details for filling semantic conventiosn for AWS Lambda ([#1442](https://github.com/open-telemetry/opentelemetry-specification/pull/1442)) +- Add details for filling semantic conventions for AWS Lambda ([#1442](https://github.com/open-telemetry/opentelemetry-specification/pull/1442)) - Update semantic conventions to distinguish between int and double ([#1550](https://github.com/open-telemetry/opentelemetry-specification/pull/1550)) ### Compatibility diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 4c341a6577d..990a6568e22 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -9,6 +9,12 @@ applicable when handlers are for HTTP requests. There are a variety of triggers for Lambda functions, and this document will grow over time to cover all the use cases. + + + +// toc goes here + + ## All triggers For all events, a span with kind `SERVER` MUST be created corresponding to the function invocation unless stated @@ -176,11 +182,11 @@ Function F: | Span ProcBatch | | `messaging.operation` | | | `process` | `process"` | `process` | | `messaging.message_id` | | | | `"a1"` | `"a2"` | -The above requires user code change to create `Span Proc1` and `Span Proc2` - in Java, the user would inherit from -[TracingSqsMessageHandler][] instead of Lambda's standard `RequestHandler` to enable them. Otherwise the spans would -not exist. +The above requires user code change to create `Span Proc1` and `Span Proc2`. In Java, the user would inherit from +[TracingSqsMessageHandler][] instead of Lambda's standard `RequestHandler` to enable them. Otherwise these two spans +would not exist. -[TracingSqsMessageHandler]: https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/aws-lambda-1.0/library/src/main/java/io/opentelemetry/instrumentation/awslambda/v1_0/TracingSqsMessageHandler.java +[TracingSqsMessageHandler]: https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/v1.0.1/instrumentation/aws-lambda-1.0/library/src/main/java/io/opentelemetry/instrumentation/awslambda/v1_0/TracingSqsMessageHandler.java ### SQS (Lambda tracing active) From 5b2bb849181c76f586f0491494912caf5847dbb2 Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Sat, 20 Mar 2021 12:45:17 +0900 Subject: [PATCH 17/19] Cleanups --- .../instrumentation/aws-lambda.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 4c341a6577d..7009e838b2f 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -147,8 +147,11 @@ Function F: | Span Function | ### API Gateway Request Proxy (Lambda tracing active) Active tracing in Lambda means an API Gateway span `Span APIGW` and a Lambda runtime invocation span `Span Lambda` -will be exported to AWS X-Ray. All attributes above are the same except that in this case, the parent of `APIGW` -is `Span Client` and the parent of `Span Function` is `Span Lambda`. +will be exported to AWS X-Ray by the infrastructure (not instrumentation). All attributes above are the same +except that in this case, the parent of `APIGW` is `Span Client` and the parent of `Span Function` is +`Span Lambda`. This means the hierarchy looks like: + +Span Client --> Span APIGW --> Span Lambda --> Span Function ### SQS (Lambda tracing passive) @@ -171,9 +174,9 @@ Function F: | Span ProcBatch | | SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` | `CONSUMER` | `CONSUMER` | | Status | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` | | `messaging.system` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | -| `messaging.destination` | `Q` | `Q` | | `Q` | `Q` | +| `messaging.destination` | `Q` | `Q` | | `Q` | `Q` | `Q` | | `messaging.destination_kind` | `queue` | `queue` | `queue` | `queue` | `queue` | -| `messaging.operation` | | | `process` | `process"` | `process` | +| `messaging.operation` | | | `process` | `process` | `process` | | `messaging.message_id` | | | | `"a1"` | `"a2"` | The above requires user code change to create `Span Proc1` and `Span Proc2` - in Java, the user would inherit from @@ -184,5 +187,9 @@ not exist. ### SQS (Lambda tracing active) -Active tracing in Lambda means a Lambda runtime invocation span `Span Lambda` will be exported to X-Ray. In this -case, all of the above is the same except `Span ProcBatch` will have a parent of `Span Lambda`. +Active tracing in Lambda means a Lambda runtime invocation span `Span Lambda` will be exported to X-Ray by the +infrastructure (not instrumentation). In this case, all of the above is the same except `Span ProcBatch` will +have a parent of `Span Lambda`. This means the hierarchy looks like: + +Span Lambda --> Span ProcBatch --> Span Proc1 (links to Span Prod1 and Span Prod2) + \-> Span Proc2 (links to Span Prod1 and Span Prod2) From ca27d56fff65da9c08c17656e3a7ad33fe09ff5a Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Sat, 20 Mar 2021 12:46:36 +0900 Subject: [PATCH 18/19] TOC --- .../instrumentation/aws-lambda.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 991fb3a3d1d..dc6694cef8e 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -9,10 +9,22 @@ applicable when handlers are for HTTP requests. There are a variety of triggers for Lambda functions, and this document will grow over time to cover all the use cases. - + -// toc goes here + +- [All triggers](#all-triggers) + * [Determining the parent of a span](#determining-the-parent-of-a-span) +- [API Gateway](#api-gateway) +- [SQS](#sqs) + * [SQS Event](#sqs-event) + * [SQS Message](#sqs-message) +- [Examples](#examples) + * [API Gateway Request Proxy (Lambda tracing passive)](#api-gateway-request-proxy-lambda-tracing-passive) + * [API Gateway Request Proxy (Lambda tracing active)](#api-gateway-request-proxy-lambda-tracing-active) + * [SQS (Lambda tracing passive)](#sqs-lambda-tracing-passive) + * [SQS (Lambda tracing active)](#sqs-lambda-tracing-active) + ## All triggers From 77a4edfebb12b9aed3a4f530d97eba1abfed2ca7 Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Tue, 23 Mar 2021 11:24:43 +0900 Subject: [PATCH 19/19] Cleanups --- .../semantic_conventions/instrumentation/aws-lambda.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index dc6694cef8e..9814df780d8 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -169,7 +169,9 @@ will be exported to AWS X-Ray by the infrastructure (not instrumentation). All a except that in this case, the parent of `APIGW` is `Span Client` and the parent of `Span Function` is `Span Lambda`. This means the hierarchy looks like: +``` Span Client --> Span APIGW --> Span Lambda --> Span Function +``` ### SQS (Lambda tracing passive) @@ -192,11 +194,14 @@ Function F: | Span ProcBatch | | SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` | `CONSUMER` | `CONSUMER` | | Status | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` | | `messaging.system` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | -| `messaging.destination` | `Q` | `Q` | | `Q` | `Q` | `Q` | +| `messaging.destination` | `Q` | `Q` | `Q` | `Q` | `Q` | | `messaging.destination_kind` | `queue` | `queue` | `queue` | `queue` | `queue` | | `messaging.operation` | | | `process` | `process` | `process` | | `messaging.message_id` | | | | `"a1"` | `"a2"` | +Note that if Span Prod1 and Span Prod2 were sent to different queues, Span ProcBatch would not have +`messaging.destination` set as it would correspond to multiple destinations. + The above requires user code change to create `Span Proc1` and `Span Proc2`. In Java, the user would inherit from [TracingSqsMessageHandler][] instead of Lambda's standard `RequestHandler` to enable them. Otherwise these two spans would not exist. @@ -209,5 +214,7 @@ Active tracing in Lambda means a Lambda runtime invocation span `Span Lambda` wi infrastructure (not instrumentation). In this case, all of the above is the same except `Span ProcBatch` will have a parent of `Span Lambda`. This means the hierarchy looks like: +``` Span Lambda --> Span ProcBatch --> Span Proc1 (links to Span Prod1 and Span Prod2) \-> Span Proc2 (links to Span Prod1 and Span Prod2) +```