Expand scope of faas.id to cloud.resource_id

As per the discussion on #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.
open-telemetry · Feb 14, 2023 · a2db39a · a2db39a
1 parent 542fd04
commit a2db39a
Show file tree

Hide file tree

Showing 7 changed files with 58 additions and 68 deletions.
diff --git a/semantic_conventions/resource/cloud.yaml b/semantic_conventions/resource/cloud.yaml
@@ -47,6 +47,29 @@ groups:
           [Google Cloud regions](https://cloud.google.com/about/locations),
           or [Tencent Cloud regions](https://intl.cloud.tencent.com/document/product/213/6091).
         examples: ['us-central1', 'us-east-1']
+      - id: resource_id
+        type: string
+        brief: >
+          A unique identifier for a specific cloud resource.
+        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.
+          For example, with FAAS platforms, use the following guidelines:
+
+          * **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/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 | A unique identifier for a specific cloud resource. [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://intl.cloud.tencent.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.
+For example, with FAAS platforms, use the following guidelines:
+
+* **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 in MiB. [5] | `128` | 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 in MiB. [4] | `128` | 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.
+**[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.
 <!-- 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).

diff --git a/specification/trace/semantic_conventions/faas.md b/specification/trace/semantic_conventions/faas.md
@@ -121,7 +121,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 +233,5 @@ This example shows the FaaS attributes for a (non-FaaS) process hosted on Google
 | Span           | `faas.execution`        | 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"` |
diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md
@@ -37,14 +37,7 @@ Lambda `Context`.
 The following attributes SHOULD be set:
 
 - [`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 `:`
+- [`cloud.account.id`][cloud] - In some languages, this is available as an accessor on the Lambda `Context`. Otherwise, it can be parsed from the ARN 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:
@@ -54,7 +47,7 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a
 |---|---|---|---|---|
 | `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` | Recommended |
 
-**[1]:** This may be different from `faas.id` if an alias is involved.
+**[1]:** This may be different from `cloud.resource_id` if an alias is involved.
 <!-- endsemconv -->
 
 [faas]: ../faas.md (FaaS trace conventions)
@@ -173,7 +166,6 @@ 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.trigger` | | `http` |
 | `cloud.account.id` | | `12345678912` |
 | `net.peer.name` | `foo.execute-api.us-east-1.amazonaws.com` |  |
@@ -255,7 +247,4 @@ AWS Lambda resource information is available as [environment variables][] provid
 - [`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`][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