From 71d6dac28d649a815d2b05b4b18bcddb330e8532 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 8 Feb 2023 12:26:12 -0500 Subject: [PATCH 01/10] 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. --- semantic_conventions/resource/cloud.yaml | 26 +++++++++++++++ semantic_conventions/resource/faas.yaml | 24 +------------- semantic_conventions/trace/aws/lambda.yaml | 2 +- .../resource/semantic_conventions/cloud.md | 27 +++++++++++++--- .../resource/semantic_conventions/faas.md | 32 ++++--------------- .../trace/semantic_conventions/faas.md | 3 +- .../instrumentation/aws-lambda.md | 15 ++------- 7 files changed, 61 insertions(+), 68 deletions(-) diff --git a/semantic_conventions/resource/cloud.yaml b/semantic_conventions/resource/cloud.yaml index a6ff2a22057..8f6d14e284f 100644 --- a/semantic_conventions/resource/cloud.yaml +++ b/semantic_conventions/resource/cloud.yaml @@ -47,6 +47,32 @@ 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//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 dc9bf701d77..3d7aab40a97 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/specification/resource/semantic_conventions/cloud.md b/specification/resource/semantic_conventions/cloud.md index 5fad6efb005..01876087160 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 | 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//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://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//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 6e58c5cadbd..256fde14dd1 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 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//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. +**[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 5434ce2d99e..73130a55f7b 100644 --- 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 index ac2726cfebe..7594bfc196b 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.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. [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 From 8b1704a1eeafc81ad71c828403e14c22bd134458 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 15 Feb 2023 11:13:12 -0500 Subject: [PATCH 02/10] Make resource_id description more specific MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christian Neumüller --- semantic_conventions/resource/cloud.yaml | 5 ++++- specification/resource/semantic_conventions/cloud.md | 2 +- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/semantic_conventions/resource/cloud.yaml b/semantic_conventions/resource/cloud.yaml index 8f6d14e284f..f5ea32a5878 100644 --- a/semantic_conventions/resource/cloud.yaml +++ b/semantic_conventions/resource/cloud.yaml @@ -50,7 +50,10 @@ groups: - id: resource_id type: string brief: > - A unique identifier for a specific cloud resource. + 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, + an [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. diff --git a/specification/resource/semantic_conventions/cloud.md b/specification/resource/semantic_conventions/cloud.md index 01876087160..4b65c83fb4d 100644 --- a/specification/resource/semantic_conventions/cloud.md +++ b/specification/resource/semantic_conventions/cloud.md @@ -12,7 +12,7 @@ | `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.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//resourceGroups//providers/Microsoft.Web/sites//functions/` | 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, an [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 | From 2ef3c34edaf12081f5b7950729db74169312ca63 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 15 Feb 2023 17:11:33 -0500 Subject: [PATCH 03/10] Add migration schema (assuming this is released in the next minor version) --- schemas/1.19.0 | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 schemas/1.19.0 diff --git a/schemas/1.19.0 b/schemas/1.19.0 new file mode 100644 index 00000000000..249a7e5f359 --- /dev/null +++ b/schemas/1.19.0 @@ -0,0 +1,67 @@ +file_format: 1.1.0 +schema_url: https://opentelemetry.io/schemas/1.18.0 +versions: + 1.19.0: + spans: + changes: + # 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: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2957 + - rename_attributes: + attribute_map: + messaging.consumer_id: messaging.consumer.id + messaging.protocol: net.app.protocol.name + messaging.protocol_version: net.app.protocol.version + messaging.destination: messaging.destination.name + messaging.temp_destination: messaging.destination.temporary + messaging.destination_kind: messaging.destination.kind + messaging.message_id: messaging.message.id + messaging.conversation_id: messaging.message.conversation_id + messaging.message_payload_size_bytes: messaging.message.payload_size_bytes + messaging.message_payload_compressed_size_bytes: messaging.message.payload_compressed_size_bytes + messaging.rabbitmq.routing_key: messaging.rabbitmq.destination.routing_key + messaging.kafka.message_key: messaging.kafka.message.key + messaging.kafka.partition: messaging.kafka.destination.partition + messaging.kafka.tombstone: messaging.kafka.message.tombstone + messaging.rocketmq.message_type: messaging.rocketmq.message.type + messaging.rocketmq.message_tag: messaging.rocketmq.message.tag + messaging.rocketmq.message_keys: messaging.rocketmq.message.keys + messaging.kafka.consumer_group: messaging.kafka.consumer.group + 1.16.0: + 1.15.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2743 + - rename_attributes: + attribute_map: + http.retry_count: http.resend_count + 1.14.0: + 1.13.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2614 + - rename_attributes: + attribute_map: + net.peer.ip: net.sock.peer.addr + net.host.ip: net.sock.host.addr + 1.12.0: + 1.11.0: + 1.10.0: + 1.9.0: + 1.8.0: + spans: + changes: + - rename_attributes: + attribute_map: + db.cassandra.keyspace: db.name + db.hbase.namespace: db.name + 1.7.0: + 1.6.1: + 1.5.0: + 1.4.0: From 057e0c3e0ad20bdfdcf3844f6806ce4e382047cb Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 16 Feb 2023 11:53:08 -0500 Subject: [PATCH 04/10] an -> a Co-authored-by: Tyler Yahn --- specification/resource/semantic_conventions/cloud.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/resource/semantic_conventions/cloud.md b/specification/resource/semantic_conventions/cloud.md index 4b65c83fb4d..250af6599ba 100644 --- a/specification/resource/semantic_conventions/cloud.md +++ b/specification/resource/semantic_conventions/cloud.md @@ -12,7 +12,7 @@ | `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.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, an [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.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 | From 1e8ca69300e5e0c54e5bad34b5440913a8c60e3b Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 16 Feb 2023 15:42:18 -0500 Subject: [PATCH 05/10] Fix schema_url --- schemas/1.19.0 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schemas/1.19.0 b/schemas/1.19.0 index 249a7e5f359..20af36ad8b3 100644 --- a/schemas/1.19.0 +++ b/schemas/1.19.0 @@ -1,5 +1,5 @@ file_format: 1.1.0 -schema_url: https://opentelemetry.io/schemas/1.18.0 +schema_url: https://opentelemetry.io/schemas/1.19.0 versions: 1.19.0: spans: From 89a82079a1ed595449590c4ffcbe3cd8b53c4793 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 16 Feb 2023 15:54:32 -0500 Subject: [PATCH 06/10] an -> a --- semantic_conventions/resource/cloud.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic_conventions/resource/cloud.yaml b/semantic_conventions/resource/cloud.yaml index f5ea32a5878..bfc648f48b3 100644 --- a/semantic_conventions/resource/cloud.yaml +++ b/semantic_conventions/resource/cloud.yaml @@ -52,7 +52,7 @@ groups: 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, - an [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, + 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, From 8b51c246bc57c5a111029becb58f795cae7f590f Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 16 Feb 2023 17:08:45 -0500 Subject: [PATCH 07/10] Added `ref: cloud.resource_id` --- semantic_conventions/trace/faas.yaml | 2 +- .../trace/semantic_conventions/faas.md | 19 +++++++++++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/semantic_conventions/trace/faas.yaml b/semantic_conventions/trace/faas.yaml index fac000a7cef..2c4468828a2 100644 --- a/semantic_conventions/trace/faas.yaml +++ b/semantic_conventions/trace/faas.yaml @@ -41,7 +41,7 @@ groups: type: string brief: 'The execution ID of the current function execution.' examples: 'af9d5aa4-a685-4c5f-a22b-444f80b3cc28' - + - ref: cloud.resource_id - id: faas_span.datasource prefix: faas.document type: span diff --git a/specification/trace/semantic_conventions/faas.md b/specification/trace/semantic_conventions/faas.md index 73130a55f7b..f86bca775ac 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 execution. [1] | `datasource` | Recommended | | `faas.execution` | string | The execution ID of the current function execution. | `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. +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//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 | From 873fda5f769a5f010cb8947810906eabca880492 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 16 Feb 2023 17:12:15 -0500 Subject: [PATCH 08/10] Apply stronger wording. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christian Neumüller --- semantic_conventions/resource/cloud.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic_conventions/resource/cloud.yaml b/semantic_conventions/resource/cloud.yaml index bfc648f48b3..88b6e1f86e1 100644 --- a/semantic_conventions/resource/cloud.yaml +++ b/semantic_conventions/resource/cloud.yaml @@ -59,7 +59,7 @@ groups: 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: + 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 From a75e2535023c81fc17d47629abb1839d4a2d4c50 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Tue, 21 Feb 2023 11:33:33 -0500 Subject: [PATCH 09/10] Fix yaml format/alignment --- semantic_conventions/resource/cloud.yaml | 2 +- specification/resource/semantic_conventions/cloud.md | 2 +- specification/trace/semantic_conventions/faas.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/semantic_conventions/resource/cloud.yaml b/semantic_conventions/resource/cloud.yaml index 88b6e1f86e1..73f5a67312b 100644 --- a/semantic_conventions/resource/cloud.yaml +++ b/semantic_conventions/resource/cloud.yaml @@ -59,7 +59,7 @@ groups: 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: + 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 diff --git a/specification/resource/semantic_conventions/cloud.md b/specification/resource/semantic_conventions/cloud.md index 250af6599ba..562e9f38e1c 100644 --- a/specification/resource/semantic_conventions/cloud.md +++ b/specification/resource/semantic_conventions/cloud.md @@ -22,7 +22,7 @@ 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: +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 diff --git a/specification/trace/semantic_conventions/faas.md b/specification/trace/semantic_conventions/faas.md index f86bca775ac..3ae91ddc22e 100644 --- a/specification/trace/semantic_conventions/faas.md +++ b/specification/trace/semantic_conventions/faas.md @@ -55,7 +55,7 @@ call to invoke the lambda, which is often HTTP). 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: +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 From a7fc7f618a2556e6171fd78ce02034828c0bae6c Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 22 Feb 2023 11:23:38 -0500 Subject: [PATCH 10/10] Review request --- .../trace/semantic_conventions/instrumentation/aws-lambda.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index fb7b15c3d3b..16914ea0870 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -244,4 +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 [`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