From 5874bbb0b238312835a1982d79e170446baa323f Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Mon, 27 Feb 2023 13:13:13 -0500 Subject: [PATCH] Expand scope of `faas.id` to `cloud.resource_id` (#3188) ## Changes 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. --- schemas/1.19.0 | 4 +++ semantic_conventions/resource/cloud.yaml | 29 +++++++++++++++++ semantic_conventions/resource/faas.yaml | 24 +------------- semantic_conventions/trace/aws/lambda.yaml | 2 +- semantic_conventions/trace/faas.yaml | 2 +- .../resource/semantic_conventions/cloud.md | 27 +++++++++++++--- .../resource/semantic_conventions/faas.md | 32 ++++--------------- .../trace/semantic_conventions/faas.md | 22 +++++++++++-- .../instrumentation/aws-lambda.md | 14 ++------ 9 files changed, 89 insertions(+), 67 deletions(-) diff --git a/schemas/1.19.0 b/schemas/1.19.0 index e7eea9481d5..5edbaeeb32a 100644 --- 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 index 321877ea6e5..5ee5da61284 100644 --- 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//resourceGroups//providers/Microsoft.Web/sites//functions/`. + 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//resourceGroups//providers/Microsoft.Web/sites//functions/' - id: availability_zone type: string brief: > diff --git a/semantic_conventions/resource/faas.yaml b/semantic_conventions/resource/faas.yaml index 3bc4413346f..4a7d3e4f306 100644 --- 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//resourceGroups//providers/Microsoft.Web/sites//functions/`. - 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 index 79fd709b0b6..73e77ea747d 100644 --- 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 index 1faedb129fe..d30d41920a9 100644 --- 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 index b1f725c2e6f..b8bb6e49329 100644 --- 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//resourceGroups//providers/Microsoft.Web/sites//functions/` | 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//resourceGroups//providers/Microsoft.Web/sites//functions/`. + 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 index c0556b8fcae..b707bbf0f6c 100644 --- 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//resourceGroups//providers/Microsoft.Web/sites//functions/`. - 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). 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 index c809ef1d16d..4acb5fa84d0 100644 --- 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//resourceGroups//providers/Microsoft.Web/sites//functions/` | 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//resourceGroups//providers/Microsoft.Web/sites//functions/`. + 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"` | diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 34a1362edf4..16914ea0870 100644 --- 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.invocation_id`][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. [faas]: ../faas.md (FaaS trace conventions) @@ -170,7 +163,6 @@ Function F: | Span Function | | SpanKind | `CLIENT` | `SERVER` | | Status | `Ok` | `Ok` | | `faas.invocation_id` | | `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` | | @@ -252,7 +244,7 @@ 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 +Note that [`cloud.resource_id`][cloud] currently cannot be populated as a 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