From 0b8cbc7a01d900c07c66b826238a6bd330234879 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Mon, 28 Jun 2021 19:19:26 +0200 Subject: [PATCH 1/7] Rework FaaS semantic conventions. --- CHANGELOG.md | 2 + semantic_conventions/resource/faas.yaml | 47 +++++++++++++------ semantic_conventions/trace/aws/lambda.yaml | 13 +++++ .../resource/semantic_conventions/faas.md | 32 +++++++++---- .../trace/semantic_conventions/faas.md | 2 + .../instrumentation/aws-lambda.md | 45 +++++++++++++----- 6 files changed, 106 insertions(+), 35 deletions(-) create mode 100644 semantic_conventions/trace/aws/lambda.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index 2b40bd7bbd3..fad05951325 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,8 @@ release. ### Semantic Conventions +- Clean up FaaS semantic conventions, add `aws.lambda.invoked_arn`. + ([#????](https://github.com/open-telemetry/opentelemetry-specification/pull/????)) - 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..4c760254ed5 100644 --- a/semantic_conventions/resource/faas.yaml +++ b/semantic_conventions/resource/faas.yaml @@ -8,32 +8,49 @@ groups: type: string required: always brief: > - The name of the function being executed. + The name of the single function that this runtime instance executes. examples: ['my-function'] - id: id type: string - required: always brief: > - The unique ID of the function - being executed. + The unique ID of the single function that this runtime instance executes. 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. + 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, 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:** Not applicable. Do not set this attribute. + * **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..0a389816a2d 100644 --- a/specification/resource/semantic_conventions/faas.md +++ b/specification/resource/semantic_conventions/faas.md @@ -4,20 +4,36 @@ **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. | `my-function` | Yes | +| `faas.id` | string | The unique ID of the single function that this runtime instance executes. [1] | `arn:aws:lambda:us-west-2:123456789012:function:my-function` | No | +| `faas.version` | string | The immutable version of the function being executed. [2] | `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. [3] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | No | +| `faas.max_memory` | int | The amount of memory available to the serverless function in MiB. [4] | `128` | No | + +**[1]:** 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. + +**[2]:** Depending on the cloud provider, 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:** Not applicable. Do not set this attribute. * **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. +**[3]:** * **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. +**[4]:** 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 From 690be32178936ba28cc63f3dc37275ab4b8b8f62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 29 Jun 2021 14:04:37 +0200 Subject: [PATCH 2/7] Add K_REVISON as GCF version. --- semantic_conventions/resource/faas.yaml | 3 ++- specification/resource/semantic_conventions/faas.md | 4 +++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/semantic_conventions/resource/faas.yaml b/semantic_conventions/resource/faas.yaml index 4c760254ed5..2b460f55bfd 100644 --- a/semantic_conventions/resource/faas.yaml +++ b/semantic_conventions/resource/faas.yaml @@ -40,7 +40,8 @@ groups: (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:** Not applicable. Do not set this attribute. + * **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 diff --git a/specification/resource/semantic_conventions/faas.md b/specification/resource/semantic_conventions/faas.md index 0a389816a2d..ac3b16bd6c9 100644 --- a/specification/resource/semantic_conventions/faas.md +++ b/specification/resource/semantic_conventions/faas.md @@ -29,7 +29,9 @@ On some providers, it may not be possible to determine the full ID at startup, w (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:** Not applicable. Do not set this attribute. * **Azure Functions:** Not applicable. Do not set this attribute. +* **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. **[3]:** * **AWS Lambda:** Use the (full) log stream name. From b61d692842ee2d8e8f8b22d4fef2f8fb17c00a62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 29 Jun 2021 14:09:27 +0200 Subject: [PATCH 3/7] Fix markdownlint. --- semantic_conventions/resource/faas.yaml | 5 ++--- .../resource/semantic_conventions/faas.md | 15 +++++++++++++-- 2 files changed, 15 insertions(+), 5 deletions(-) diff --git a/semantic_conventions/resource/faas.yaml b/semantic_conventions/resource/faas.yaml index 2b460f55bfd..445fc3ef96c 100644 --- a/semantic_conventions/resource/faas.yaml +++ b/semantic_conventions/resource/faas.yaml @@ -14,7 +14,7 @@ groups: type: string brief: > The unique ID of the single function that this runtime instance executes. - note: > + 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). @@ -28,12 +28,11 @@ groups: 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 immutable version of the function being executed. - note: > + note: | Depending on the cloud provider, use: * **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) diff --git a/specification/resource/semantic_conventions/faas.md b/specification/resource/semantic_conventions/faas.md index ac3b16bd6c9..5c781d46830 100644 --- a/specification/resource/semantic_conventions/faas.md +++ b/specification/resource/semantic_conventions/faas.md @@ -21,10 +21,21 @@ See also: | `faas.max_memory` | int | The amount of memory available to the serverless function in MiB. [4] | `128` | No | **[1]:** 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. + +* **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. **[2]:** Depending on the cloud provider, 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) From 5e5dc9457638f3522ee4e4748f5e7d02865b7222 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 29 Jun 2021 14:14:00 +0200 Subject: [PATCH 4/7] Fill in PR#. --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fad05951325..ec4443ab68c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,7 +25,7 @@ release. ### Semantic Conventions - Clean up FaaS semantic conventions, add `aws.lambda.invoked_arn`. - ([#????](https://github.com/open-telemetry/opentelemetry-specification/pull/????)) + ([#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)) From c10855508c30a42e4cfd1abd29b32dfb8da047f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 29 Jun 2021 14:46:33 +0200 Subject: [PATCH 5/7] Typos. --- semantic_conventions/resource/faas.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/semantic_conventions/resource/faas.yaml b/semantic_conventions/resource/faas.yaml index 445fc3ef96c..a41c8da9056 100644 --- a/semantic_conventions/resource/faas.yaml +++ b/semantic_conventions/resource/faas.yaml @@ -21,7 +21,8 @@ groups: 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). + * **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 @@ -33,7 +34,7 @@ groups: type: string brief: The immutable version of the function being executed. note: | - Depending on the cloud provider, use: + 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). From 5597a3f3869bf14171cb0f09c8b98111d00f0335 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 29 Jun 2021 14:51:15 +0200 Subject: [PATCH 6/7] Sync md --- specification/resource/semantic_conventions/faas.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/resource/semantic_conventions/faas.md b/specification/resource/semantic_conventions/faas.md index 5c781d46830..866207cfe5a 100644 --- a/specification/resource/semantic_conventions/faas.md +++ b/specification/resource/semantic_conventions/faas.md @@ -26,7 +26,8 @@ See also: 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). +* **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 @@ -34,7 +35,7 @@ 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. -**[2]:** Depending on the cloud provider, use: +**[2]:** 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). From a04630e930d6d40215ae35adba7f53b6dae78d5f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 29 Jun 2021 15:37:01 +0200 Subject: [PATCH 7/7] Clarify faas.name. --- semantic_conventions/resource/faas.yaml | 8 ++++++- .../resource/semantic_conventions/faas.md | 22 ++++++++++--------- 2 files changed, 19 insertions(+), 11 deletions(-) diff --git a/semantic_conventions/resource/faas.yaml b/semantic_conventions/resource/faas.yaml index a41c8da9056..5fe8b230298 100644 --- a/semantic_conventions/resource/faas.yaml +++ b/semantic_conventions/resource/faas.yaml @@ -9,6 +9,12 @@ groups: required: always brief: > 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 @@ -22,7 +28,7 @@ groups: [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). + * **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 diff --git a/specification/resource/semantic_conventions/faas.md b/specification/resource/semantic_conventions/faas.md index 866207cfe5a..de019bc1dac 100644 --- a/specification/resource/semantic_conventions/faas.md +++ b/specification/resource/semantic_conventions/faas.md @@ -14,20 +14,22 @@ See also: | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| -| `faas.name` | string | The name of the single function that this runtime instance executes. | `my-function` | Yes | -| `faas.id` | string | The unique ID of the single function that this runtime instance executes. [1] | `arn:aws:lambda:us-west-2:123456789012:function:my-function` | No | -| `faas.version` | string | The immutable version of the function being executed. [2] | `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. [3] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | No | -| `faas.max_memory` | int | The amount of memory available to the serverless function in MiB. [4] | `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]:** Depending on the cloud provider, use: +**[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). +* **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 @@ -35,7 +37,7 @@ 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. -**[2]:** Depending on the cloud provider and platform, use: +**[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). @@ -45,9 +47,9 @@ As an alternative, consider setting `faas.id` as a span attribute instead. [`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. -**[3]:** * **AWS Lambda:** Use the (full) log stream name. +**[4]:** * **AWS Lambda:** Use the (full) log stream name. -**[4]:** 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).