From 3cbfcad7a5e2c4c09847f20f514ca603c8504d2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 6 Jul 2021 14:34:09 +0200 Subject: [PATCH] Rework FaaS semantic conventions. (#1781) --- CHANGELOG.md | 2 + semantic_conventions/resource/faas.yaml | 56 +++++++++++++------ semantic_conventions/trace/aws/lambda.yaml | 13 +++++ .../resource/semantic_conventions/faas.md | 48 +++++++++++++--- .../trace/semantic_conventions/faas.md | 2 + .../instrumentation/aws-lambda.md | 45 +++++++++++---- 6 files changed, 130 insertions(+), 36 deletions(-) create mode 100644 semantic_conventions/trace/aws/lambda.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index 2b40bd7bbd3..ec4443ab68c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,8 @@ release. ### Semantic Conventions +- Clean up FaaS semantic conventions, add `aws.lambda.invoked_arn`. + ([#1781](https://github.com/open-telemetry/opentelemetry-specification/pull/1781)) - Remove `rpc.jsonrpc.method`, clarify that `rpc.method` should be used instead. ([#1748](https://github.com/open-telemetry/opentelemetry-specification/pull/1748)) diff --git a/semantic_conventions/resource/faas.yaml b/semantic_conventions/resource/faas.yaml index 051011944fe..5fe8b230298 100644 --- a/semantic_conventions/resource/faas.yaml +++ b/semantic_conventions/resource/faas.yaml @@ -8,32 +8,56 @@ groups: type: string required: always brief: > - The name of the function being executed. + The name of the single function that this runtime instance executes. + note: + This is the name of the function as configured/deployed on the FaaS + platform and is usually different from the name of the callback + function (which may be stored in the + [`code.namespace`/`code.function`](../../trace/semantic_conventions/span-general.md#source-code-attributes) + span attributes). examples: ['my-function'] - id: id type: string - required: always brief: > - The unique ID of the function - being executed. - note: > - 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 unique ID of the single function that this runtime instance executes. + note: | + Depending on the cloud provider, use: + + * **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). + Take care not to use the "invoked ARN" directly but replace any + [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) with the resolved function version, as the same runtime instance may be invokable with multiple + different aliases. + * **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) + * **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id). + + On some providers, it may not be possible to determine the full ID at startup, + which is why this field cannot be made required. For example, on AWS the account ID + part of the ARN is not available without calling another AWS API + which may be deemed too slow for a short-running lambda function. + As an alternative, consider setting `faas.id` as a span attribute instead. examples: ['arn:aws:lambda:us-west-2:123456789012:function:my-function'] - id: version type: string - brief: > - The version string of the function being executed as defined in - [Version Attributes](../../resource/semantic_conventions/README.md#version-attributes). - examples: ['2.0.0'] + brief: The immutable version of the function being executed. + note: | + Depending on the cloud provider and platform, use: + + * **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) + (an integer represented as a decimal string). + * **Google Cloud Run:** The [revision](https://cloud.google.com/run/docs/managing/revisions) + (i.e., the function name plus the revision suffix). + * **Google Cloud Functions:** The value of the + [`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically). + * **Azure Functions:** Not applicable. Do not set this attribute. + examples: ['26', 'pinkfroid-00002'] - id: instance type: string brief: > - The execution environment ID as a string. - examples: ['my-function:instance-0001'] + The execution environment ID as a string, that will be potentially reused + for other invocations to the same function/function version. + note: > + * **AWS Lambda:** Use the (full) log stream name. + examples: ['2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de'] - id: max_memory type: int brief: > diff --git a/semantic_conventions/trace/aws/lambda.yaml b/semantic_conventions/trace/aws/lambda.yaml new file mode 100644 index 00000000000..e9a0b0eb771 --- /dev/null +++ b/semantic_conventions/trace/aws/lambda.yaml @@ -0,0 +1,13 @@ +groups: + - id: aws.lambda + prefix: aws.lambda + brief: > + Span attributes used by AWS Lambda (in addition to general `faas` attributes). + attributes: + - id: invoked_arn + type: string + brief: > + The full invoked ARN as provided on the `Context` passed to the function + (`Lambda-Runtime-Invoked-Function-Arn` header on the `/runtime/invocation/next` applicable). + note: This may be different from `faas.id` if an alias is involved. + examples: ['arn:aws:lambda:us-east-1:123456:function:myfunction:myalias'] diff --git a/specification/resource/semantic_conventions/faas.md b/specification/resource/semantic_conventions/faas.md index 91ee3f06952..de019bc1dac 100644 --- a/specification/resource/semantic_conventions/faas.md +++ b/specification/resource/semantic_conventions/faas.md @@ -4,20 +4,52 @@ **type:** `faas` -**Description:** A serverless instance. +**Description:** A "function as a service" aka "serverless function" instance. + +See also: + +- The [Trace semantic conventions for FaaS](../../trace/semantic_conventions/faas.md) +- The [Cloud resource conventions](cloud.md) | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| -| `faas.name` | string | The name of the function being executed. | `my-function` | Yes | -| `faas.id` | string | The unique ID of the function being executed. [1] | `arn:aws:lambda:us-west-2:123456789012:function:my-function` | Yes | -| `faas.version` | string | The version string of the function being executed as defined in [Version Attributes](../../resource/semantic_conventions/README.md#version-attributes). | `2.0.0` | No | -| `faas.instance` | string | The execution environment ID as a string. | `my-function:instance-0001` | No | -| `faas.max_memory` | int | The amount of memory available to the serverless function in MiB. [2] | `128` | No | +| `faas.name` | string | The name of the single function that this runtime instance executes. [1] | `my-function` | Yes | +| `faas.id` | string | The unique ID of the single function that this runtime instance executes. [2] | `arn:aws:lambda:us-west-2:123456789012:function:my-function` | No | +| `faas.version` | string | The immutable version of the function being executed. [3] | `26`; `pinkfroid-00002` | No | +| `faas.instance` | string | The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version. [4] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | No | +| `faas.max_memory` | int | The amount of memory available to the serverless function in MiB. [5] | `128` | No | + +**[1]:** This is the name of the function as configured/deployed on the FaaS platform and is usually different from the name of the callback function (which may be stored in the [`code.namespace`/`code.function`](../../trace/semantic_conventions/span-general.md#source-code-attributes) span attributes). + +**[2]:** Depending on the cloud provider, use: + +* **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). +Take care not to use the "invoked ARN" directly but replace any +[alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) with the resolved function version, as the same runtime instance may be invokable with multiple +different aliases. +* **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) +* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id). + +On some providers, it may not be possible to determine the full ID at startup, +which is why this field cannot be made required. For example, on AWS the account ID +part of the ARN is not available without calling another AWS API +which may be deemed too slow for a short-running lambda function. +As an alternative, consider setting `faas.id` as a span attribute instead. + +**[3]:** Depending on the cloud provider and platform, use: + +* **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) + (an integer represented as a decimal string). +* **Google Cloud Run:** The [revision](https://cloud.google.com/run/docs/managing/revisions) + (i.e., the function name plus the revision suffix). +* **Google Cloud Functions:** The value of the + [`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically). +* **Azure Functions:** Not applicable. Do not set this attribute. -**[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. +**[4]:** * **AWS Lambda:** Use the (full) log stream name. -**[2]:** It's recommended to set this attribute since e.g. too little memory can easily stop a Java AWS Lambda function from working correctly. On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` provides this information. +**[5]:** It's recommended to set this attribute since e.g. too little memory can easily stop a Java AWS Lambda function from working correctly. On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` provides this information. Note: The resource attribute `faas.instance` differs from the span attribute `faas.execution`. For more information see the [Semantic conventions for FaaS spans](../../trace/semantic_conventions/faas.md#difference-between-execution-and-instance). diff --git a/specification/trace/semantic_conventions/faas.md b/specification/trace/semantic_conventions/faas.md index 00b29831a47..1f93e76d9b0 100644 --- a/specification/trace/semantic_conventions/faas.md +++ b/specification/trace/semantic_conventions/faas.md @@ -5,6 +5,8 @@ This document defines how to describe an instance of a function that runs without provisioning or managing of servers (also known as serverless functions or Function as a Service (FaaS)) with spans. +See also the [additional instructions for instrumenting AWS Lambda](instrumentation/aws-lambda.md). + diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index e61ec2822c9..d76045d7b70 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -3,7 +3,7 @@ **Status**: [Experimental](../../../document-status.md) 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 +Lambda largely follows the conventions for [FaaS][faas] 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 @@ -35,9 +35,30 @@ Lambda `Context`. 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` -- [`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 `:` +- [`faas.execution`][faas] - The value of the AWS Request ID, which is always available through an accessor on the Lambda `Context`. +- [`faas.id`][faasres] - The value of the invocation ARN + for the function, which is always available through an accessor on the + Lambda `Context`, modified as follows: Discard all parts beyond the seventh (when split on `:`; + the seventh part is the function name) and append the [`faas.version`][faasres], separated by a colon. + + Note that this is set as span attribute instead of resource attribute due to technical limitations + (account ID is not available at startup). +- [`cloud.account.id`][cloud] - 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 `:` + +Also consider setting other attributes of the [`faas` resource][faasres] and [trace][faas] conventions +and the [cloud resource conventions][cloud]. The following AWS Lambda-specific attribute MAY also be set: + + +| Attribute | Type | Description | Examples | Required | +|---|---|---|---|---| +| `aws.lambda.invoked_arn` | string | The full invoked ARN as provided on the `Context` passed to the function (`Lambda-Runtime-Invoked-Function-Arn` header on the `/runtime/invocation/next` applicable). [1] | `arn:aws:lambda:us-east-1:123456:function:myfunction:myalias` | No | + +**[1]:** This may be different from `faas.id` if an alias is involved. + + +[faas]: ../faas.md (FaaS trace conventions) +[faasres]: ../../../resource/semantic_conventions/faas.md (FaaS resource conventions) +[cloud]: ../../../resource/semantic_conventions/cloud.md (Cloud resource conventions) ### Determining the parent of a span @@ -65,7 +86,7 @@ The Lambda span name and the [`http.route` span attribute](../http.md#http-serve 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 +[`faas.trigger`][faas] MUST be set to `http`. [HTTP attributes](../http.md) SHOULD be set based on the 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. @@ -95,7 +116,7 @@ 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`. +- [`faas.trigger`][faas]] 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`. @@ -108,7 +129,7 @@ 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`. +- [`faas.trigger`][faas] 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`. @@ -223,12 +244,12 @@ Span Lambda --> Span ProcBatch --> Span Proc1 (links to Span Prod1 and Span Prod AWS Lambda resource information is available as [environment variables][] provided by the runtime. -- [`cloud.provider`](../../../resource/semantic_conventions/cloud.md) MUST be set to `aws` -- [`cloud.region`](../../../resource/semantic_conventions/cloud.md) MUST be set to the value of the `AWS_REGION` environment variable -- [`faas.name`](../../../resource/semantic_conventions/faas.md) MUST be set to the value of the `AWS_LAMBDA_FUNCTION_NAME` environment variable -- [`faas.version`](../../../resource/semantic_conventions/faas.md) MUST be set to the value of the `AWS_LAMBDA_FUNCTION_VERSION` environment variable +- [`cloud.provider`][cloud] MUST be set to `aws` +- [`cloud.region`][cloud] MUST be set to the value of the `AWS_REGION` environment variable +- [`faas.name`][faasres] MUST be set to the value of the `AWS_LAMBDA_FUNCTION_NAME` environment variable +- [`faas.version`][faasres] MUST be set to the value of the `AWS_LAMBDA_FUNCTION_VERSION` environment variable -Note that [`faas.id`](../../../resource/semantic_conventions/faas.md) currently cannot be populated to resource +Note that [`faas.id`][faasres] currently cannot be populated to resource because it is not available until function invocation. [environment variables]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime