Expand scope of faas.id to cloud.resource_id (open-telemetry#3188)

## Changes As per the discussion on open-telemetry#3188, we determined it is better to move rather than remove as this attribute is still important for some systems despite it containing duplicated information.
carlosalberto · Feb 27, 2023 · fa86e5f · fa86e5f
1 parent 5299019
commit fa86e5f
Show file tree

Hide file tree

Showing 9 changed files with 89 additions and 67 deletions.
diff --git a/schemas/1.19.0 b/schemas/1.19.0
@@ -8,6 +8,10 @@ versions:
         - rename_attributes:
             attribute_map:
               faas.execution: faas.invocation_id
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3188
+        - rename_attributes:
+            attribute_map:
+              faas.id: cloud.resource_id
   1.18.0:
   1.17.0:
     spans:

diff --git a/semantic_conventions/resource/cloud.yaml b/semantic_conventions/resource/cloud.yaml
@@ -50,6 +50,35 @@ groups:
           [Google Cloud regions](https://cloud.google.com/about/locations),
           or [Tencent Cloud regions](https://www.tencentcloud.com/document/product/213/6091).
         examples: ['us-central1', 'us-east-1']
+      - id: resource_id
+        type: string
+        brief: >
+          Cloud provider-specific native identifier of the monitored cloud resource
+          (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS,
+          a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure,
+          a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP)
+        note: |
+          On some cloud providers, it may not be possible to determine the full ID at startup,
+          so it may be necessary to set `cloud.resource_id` as a span attribute instead.
+
+          The exact value to use for `cloud.resource_id` depends on the cloud provider.
+          The following well-known definitions MUST be used if you set this attribute and they apply:
+
+          * **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) of the invoked function,
+            *not* the function app, having the form
+            `/subscriptions/<SUBSCIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>`.
+            This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share
+            a TracerProvider.
+        examples:
+          - 'arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function'
+          - '//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID'
+          - '/subscriptions/<SUBSCIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>'
       - id: availability_zone
         type: string
         brief: >

diff --git a/semantic_conventions/resource/faas.yaml b/semantic_conventions/resource/faas.yaml
@@ -26,30 +26,8 @@ groups:
             can also be seen in the resource JSON for the function).
             This means that a span attribute MUST be used, as an Azure function
             app can host multiple functions that would usually share
-            a TracerProvider (see also the `faas.id` attribute).
+            a TracerProvider (see also the `cloud.resource_id` attribute).
         examples: ['my-function', 'myazurefunctionapp/some-function-name']
-      - id: id
-        type: string
-        brief: >
-          The unique ID of the single function that this runtime instance executes.
-        note: |
-          On some cloud providers, it may not be possible to determine the full ID at startup,
-          so consider setting `faas.id` as a span attribute instead.
-
-          The exact value to use for `faas.id` depends on the cloud provider:
-
-          * **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) of the invoked function,
-            *not* the function app, having the form
-            `/subscriptions/<SUBSCIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>`.
-            This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share
-            a TracerProvider.
-        examples: ['arn:aws:lambda:us-west-2:123456789012:function:my-function']
       - id: version
         type: string
         brief: The immutable version of the function being executed.

diff --git a/semantic_conventions/trace/aws/lambda.yaml b/semantic_conventions/trace/aws/lambda.yaml
@@ -10,5 +10,5 @@ groups:
         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.
+        note: This may be different from `cloud.resource_id` if an alias is involved.
         examples: ['arn:aws:lambda:us-east-1:123456:function:myfunction:myalias']
diff --git a/semantic_conventions/trace/faas.yaml b/semantic_conventions/trace/faas.yaml
@@ -41,7 +41,7 @@ groups:
         type: string
         brief: 'The invocation ID of the current function invocation.'
         examples: 'af9d5aa4-a685-4c5f-a22b-444f80b3cc28'
-
+      - ref: cloud.resource_id
   - id: faas_span.datasource
     prefix: faas.document
     type: span

diff --git a/specification/resource/semantic_conventions/cloud.md b/specification/resource/semantic_conventions/cloud.md
@@ -12,14 +12,33 @@
 | `cloud.provider` | string | Name of the cloud provider. | `alibaba_cloud` | Recommended |
 | `cloud.account.id` | string | The cloud account ID the resource is assigned to. | `111111111111`; `opentelemetry` | Recommended |
 | `cloud.region` | string | The geographical region the resource is running. [1] | `us-central1`; `us-east-1` | Recommended |
-| `cloud.availability_zone` | string | Cloud regions often have multiple, isolated locations known as zones to increase availability. Availability zone represents the zone where the resource is running. [2] | `us-east-1c` | Recommended |
-| `cloud.platform` | string | The cloud platform in use. [3] | `alibaba_cloud_ecs` | Recommended |
+| `cloud.resource_id` | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [2] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions/<SUBSCIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>` | Recommended |
+| `cloud.availability_zone` | string | Cloud regions often have multiple, isolated locations known as zones to increase availability. Availability zone represents the zone where the resource is running. [3] | `us-east-1c` | Recommended |
+| `cloud.platform` | string | The cloud platform in use. [4] | `alibaba_cloud_ecs` | Recommended |
 
 **[1]:** Refer to your provider's docs to see the available regions, for example [Alibaba Cloud regions](https://www.alibabacloud.com/help/doc-detail/40654.htm), [AWS regions](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/), [Azure regions](https://azure.microsoft.com/en-us/global-infrastructure/geographies/), [Google Cloud regions](https://cloud.google.com/about/locations), or [Tencent Cloud regions](https://www.tencentcloud.com/document/product/213/6091).
 
-**[2]:** Availability zones are called "zones" on Alibaba Cloud and Google Cloud.
+**[2]:** On some cloud providers, it may not be possible to determine the full ID at startup,
+so it may be necessary to set `cloud.resource_id` as a span attribute instead.
 
-**[3]:** The prefix of the service SHOULD match the one specified in `cloud.provider`.
+The exact value to use for `cloud.resource_id` depends on the cloud provider.
+The following well-known definitions MUST be used if you set this attribute and they apply:
+
+* **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) of the invoked function,
+  *not* the function app, having the form
+  `/subscriptions/<SUBSCIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>`.
+  This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share
+  a TracerProvider.
+
+**[3]:** Availability zones are called "zones" on Alibaba Cloud and Google Cloud.
+
+**[4]:** The prefix of the service SHOULD match the one specified in `cloud.provider`.
 
 `cloud.provider` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
 

diff --git a/specification/resource/semantic_conventions/faas.md b/specification/resource/semantic_conventions/faas.md
@@ -17,10 +17,9 @@ See also:
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | `faas.name` | string | The name of the single function that this runtime instance executes. [1] | `my-function`; `myazurefunctionapp/some-function-name` | Required |
-| `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` | Recommended |
-| `faas.version` | string | The immutable version of the function being executed. [3] | `26`; `pinkfroid-00002` | Recommended |
-| `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` | Recommended |
-| `faas.max_memory` | int | The amount of memory available to the serverless function converted to Bytes. [5] | `134217728` | Recommended |
+| `faas.version` | string | The immutable version of the function being executed. [2] | `26`; `pinkfroid-00002` | Recommended |
+| `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` | Recommended |
+| `faas.max_memory` | int | The amount of memory available to the serverless function converted to Bytes. [4] | `134217728` | Recommended |
 
 **[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
@@ -37,26 +36,9 @@ definition of function name MUST be used for this attribute
   can also be seen in the resource JSON for the function).
   This means that a span attribute MUST be used, as an Azure function
   app can host multiple functions that would usually share
-  a TracerProvider (see also the `faas.id` attribute).
+  a TracerProvider (see also the `cloud.resource_id` attribute).
 
-**[2]:** On some cloud providers, it may not be possible to determine the full ID at startup,
-so consider setting `faas.id` as a span attribute instead.
-
-The exact value to use for `faas.id` depends on the cloud provider:
-
-* **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) of the invoked function,
-  *not* the function app, having the form
-  `/subscriptions/<SUBSCIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>`.
-  This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share
-  a TracerProvider.
-
-**[3]:** Depending on the cloud provider and platform, 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).
@@ -66,9 +48,9 @@ The exact value to use for `faas.id` depends on the cloud provider:
   [`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.
 
-**[4]:** * **AWS Lambda:** Use the (full) log stream name.
+**[3]:** * **AWS Lambda:** Use the (full) log stream name.
 
-**[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 (which must be multiplied by 1,048,576).
+**[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 (which must be multiplied by 1,048,576).
 <!-- endsemconv -->
 
 Note: The resource attribute `faas.instance` differs from the span attribute `faas.invocation_id`. For more information see the [Semantic conventions for FaaS spans](../../trace/semantic_conventions/faas.md#difference-between-invocation-and-instance).

diff --git a/specification/trace/semantic_conventions/faas.md b/specification/trace/semantic_conventions/faas.md
@@ -39,6 +39,7 @@ If Spans following this convention are produced, a Resource of type `faas` MUST
 |---|---|---|---|---|
 | `faas.trigger` | string | Type of the trigger which caused this function invocation. [1] | `datasource` | Recommended |
 | `faas.invocation_id` | string | The invocation ID of the current function invocation. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | Recommended |
+| [`cloud.resource_id`](../../resource/semantic_conventions/cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [2] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions/<SUBSCIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>` | Recommended |
 
 **[1]:** For the server/consumer span on the incoming side,
 `faas.trigger` MUST be set.
@@ -50,6 +51,24 @@ trigger that corresponding incoming would have (i.e., this has
 nothing to do with the underlying transport used to make the API
 call to invoke the lambda, which is often HTTP).
 
+**[2]:** On some cloud providers, it may not be possible to determine the full ID at startup,
+so it may be necessary to set `cloud.resource_id` as a span attribute instead.
+
+The exact value to use for `cloud.resource_id` depends on the cloud provider.
+The following well-known definitions MUST be used if you set this attribute and they apply:
+
+* **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) of the invoked function,
+  *not* the function app, having the form
+  `/subscriptions/<SUBSCIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>`.
+  This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share
+  a TracerProvider.
+
 `faas.trigger` MUST be one of the following:
 
 | Value  | Description |
@@ -121,7 +140,7 @@ FaaS environments some of the information required for resource
 attributes is only readily available in the context of an invocation (e.g. as part of a "request context" argument)
 and while a separate API call to look up the resource information is often possible, it
 may be prohibitively expensive due to cold start duration concerns.
-The `faas.id` and `cloud.account.id` attributes on AWS are some examples.
+The `cloud.resource_id` and `cloud.account.id` attributes on AWS are some examples.
 In principle, the above considerations apply to any resource attribute that fulfills the criteria above
 (not being readily available without some extra effort that could be expensive).
 
@@ -233,6 +252,5 @@ This example shows the FaaS attributes for a (non-FaaS) process hosted on Google
 | Span           | `faas.invocation_id`    | n/a                    | `"af9d5aa4-a685-4c5f-a22b-444f80b3cc28"` |
 | Span           | `faas.coldstart`        | n/a                    | `true` |
 | Resource       | `faas.name`             | n/a                    | `"my-lambda-function"` |
-| Resource       | `faas.id`               | n/a                    | `"arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function"` |
 | Resource       | `faas.version`          | n/a                    | `"semver:2.0.0"` |
 | Resource       | `faas.instance`         | n/a                    | `"my-lambda-function:instance-0001"` |