Rework FaaS semantic conventions. (#1781)

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

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: >

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']

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)
 
 <!-- semconv faas_resource -->
 | 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.
 <!-- endsemconv -->
 
 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).

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).
+
 <!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
 
 <!-- toc -->

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:
+
+<!-- semconv aws.lambda -->
+| 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.
+<!-- endsemconv -->
+
+[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