From 2afe58c54ad22a388a37643c7b342638a160734b Mon Sep 17 00:00:00 2001
From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Date: Mon, 18 Nov 2024 11:14:30 +0100
Subject: [PATCH 01/32] [chore] Render attribute name on foot notes (#1583)
---
docs/attributes-registry/android.md | 2 +-
docs/attributes-registry/artifact.md | 4 +-
docs/attributes-registry/aws.md | 20 +--
docs/attributes-registry/browser.md | 8 +-
docs/attributes-registry/client.md | 4 +-
docs/attributes-registry/cloud.md | 8 +-
docs/attributes-registry/cloudfoundry.md | 22 ++--
docs/attributes-registry/container.md | 10 +-
docs/attributes-registry/db.md | 20 +--
docs/attributes-registry/deployment.md | 2 +-
docs/attributes-registry/destination.md | 2 +-
docs/attributes-registry/device.md | 8 +-
docs/attributes-registry/dns.md | 2 +-
docs/attributes-registry/error.md | 2 +-
docs/attributes-registry/event.md | 2 +-
docs/attributes-registry/exception.md | 2 +-
docs/attributes-registry/faas.md | 14 +--
docs/attributes-registry/feature-flag.md | 2 +-
docs/attributes-registry/file.md | 14 +--
docs/attributes-registry/gcp.md | 2 +-
docs/attributes-registry/gen-ai.md | 4 +-
docs/attributes-registry/graphql.md | 2 +-
docs/attributes-registry/hardware.md | 2 +-
docs/attributes-registry/host.md | 6 +-
docs/attributes-registry/http.md | 10 +-
docs/attributes-registry/ios.md | 2 +-
docs/attributes-registry/jvm.md | 8 +-
docs/attributes-registry/k8s.md | 2 +-
docs/attributes-registry/log.md | 4 +-
docs/attributes-registry/messaging.md | 20 +--
docs/attributes-registry/network.md | 8 +-
docs/attributes-registry/oci.md | 2 +-
docs/attributes-registry/opentracing.md | 2 +-
docs/attributes-registry/process.md | 6 +-
docs/attributes-registry/rpc.md | 14 +--
docs/attributes-registry/server.md | 4 +-
docs/attributes-registry/service.md | 6 +-
docs/attributes-registry/source.md | 2 +-
docs/attributes-registry/telemetry.md | 4 +-
docs/attributes-registry/tls.md | 2 +-
docs/attributes-registry/url.md | 18 +--
docs/attributes-registry/user-agent.md | 4 +-
docs/attributes-registry/user.md | 2 +-
docs/attributes-registry/v8js.md | 2 +-
docs/attributes-registry/vcs.md | 4 +-
docs/cloud-providers/aws-sdk.md | 4 +-
docs/database/cassandra.md | 24 ++--
docs/database/cosmosdb.md | 40 +++---
docs/database/couchdb.md | 12 +-
docs/database/database-metrics.md | 44 +++----
docs/database/database-spans.md | 26 ++--
docs/database/dynamodb.md | 52 ++++----
docs/database/elasticsearch.md | 26 ++--
docs/database/hbase.md | 16 +--
docs/database/mariadb.md | 22 ++--
docs/database/mongodb.md | 14 +--
docs/database/mssql.md | 22 ++--
docs/database/mysql.md | 22 ++--
docs/database/postgresql.md | 22 ++--
docs/database/redis.md | 20 +--
docs/database/sql.md | 22 ++--
docs/dns/dns-metrics.md | 4 +-
docs/dotnet/dotnet-aspnetcore-metrics.md | 4 +-
docs/dotnet/dotnet-kestrel-metrics.md | 76 ++++++------
docs/exceptions/exceptions-spans.md | 2 +-
docs/faas/aws-lambda.md | 2 +-
docs/faas/faas-spans.md | 12 +-
docs/feature-flags/feature-flags-logs.md | 4 +-
docs/gen-ai/azure-ai-inference.md | 14 +--
docs/gen-ai/gen-ai-events.md | 2 +-
docs/gen-ai/gen-ai-metrics.md | 44 +++----
docs/gen-ai/gen-ai-spans.md | 14 +--
docs/gen-ai/openai.md | 12 +-
docs/general/attributes.md | 20 +--
docs/general/events.md | 2 +-
docs/general/logs.md | 4 +-
docs/general/trace-compatibility.md | 2 +-
docs/graphql/graphql-spans.md | 2 +-
docs/hardware/common.md | 12 +-
docs/http/http-metrics.md | 116 +++++++++---------
docs/http/http-spans.md | 54 ++++----
docs/messaging/azure-messaging.md | 28 ++---
docs/messaging/gcp-pubsub.md | 14 +--
docs/messaging/kafka.md | 16 +--
docs/messaging/messaging-metrics.md | 62 +++++-----
docs/messaging/messaging-spans.md | 26 ++--
docs/messaging/rabbitmq.md | 14 +--
docs/messaging/rocketmq.md | 14 +--
docs/object-stores/s3.md | 16 +--
docs/resource/README.md | 10 +-
docs/resource/browser.md | 10 +-
docs/resource/cloud-provider/aws/logs.md | 6 +-
docs/resource/cloud.md | 8 +-
docs/resource/cloudfoundry.md | 20 +--
docs/resource/container.md | 8 +-
docs/resource/deployment-environment.md | 2 +-
docs/resource/device.md | 8 +-
docs/resource/faas.md | 10 +-
docs/resource/host.md | 8 +-
docs/resource/k8s.md | 2 +-
docs/resource/os.md | 2 +-
docs/rpc/connect-rpc.md | 4 +-
docs/rpc/grpc.md | 4 +-
docs/rpc/json-rpc.md | 2 +-
docs/rpc/rpc-metrics.md | 12 +-
docs/rpc/rpc-spans.md | 30 ++---
docs/runtime/jvm-metrics.md | 20 +--
docs/runtime/v8js-metrics.md | 8 +-
docs/system/container-metrics.md | 4 +-
docs/system/process-metrics.md | 4 +-
docs/system/system-metrics.md | 6 +-
docs/url/url.md | 6 +-
.../markdown/attribute_namespace.md.j2 | 2 +-
.../registry/markdown/attribute_table.j2 | 2 +-
.../registry/markdown/body_field_table.j2 | 2 +-
templates/registry/markdown/enum_macros.j2 | 4 +-
templates/registry/markdown/metric_table.j2 | 2 +-
templates/registry/markdown/notes.j2 | 6 +-
templates/registry/markdown/requirement.j2 | 4 +-
119 files changed, 743 insertions(+), 743 deletions(-)
diff --git a/docs/attributes-registry/android.md b/docs/attributes-registry/android.md
index 4870e52fe3..ce172dacd5 100644
--- a/docs/attributes-registry/android.md
+++ b/docs/attributes-registry/android.md
@@ -25,7 +25,7 @@ This document defines attributes that represents an occurrence of a lifecycle tr
|---|---|---|---|---|
| `android.state` | string | Deprecated use the `device.app.lifecycle` event definition including `android.state` as a payload field instead. [1] | `created`; `background`; `foreground` | 
Replaced by `device.app.lifecycle`. |
-**[1]:** The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived.
+**[1] `android.state`:** The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived.
`android.state` 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/docs/attributes-registry/artifact.md b/docs/attributes-registry/artifact.md
index e4b2b72ece..4006920b1c 100644
--- a/docs/attributes-registry/artifact.md
+++ b/docs/attributes-registry/artifact.md
@@ -20,12 +20,12 @@ This group describes attributes specific to artifacts. Artifacts are files or ot
| `artifact.purl` | string | The [Package URL](https://github.com/package-url/purl-spec) of the [package artifact](https://slsa.dev/spec/v1.0/terminology#package-model) provides a standard way to identify and locate the packaged artifact. | `pkg:github/package-url/purl-spec@1209109710924`; `pkg:npm/foo@12.12.3` |  |
| `artifact.version` | string | The version of the artifact. | `v0.1.0`; `1.2.1`; `122691-build` |  |
-**[1]:** This file name can also act as the [Package Name](https://slsa.dev/spec/v1.0/terminology#package-model)
+**[1] `artifact.filename`:** This file name can also act as the [Package Name](https://slsa.dev/spec/v1.0/terminology#package-model)
in cases where the package ecosystem maps accordingly.
Additionally, the artifact [can be published](https://slsa.dev/spec/v1.0/terminology#software-supply-chain)
for others, but that is not a guarantee.
-**[2]:** The specific algorithm used to create the cryptographic hash value is
+**[2] `artifact.hash`:** The specific algorithm used to create the cryptographic hash value is
not defined. In situations where an artifact has multiple
cryptographic hashes, it is up to the implementer to choose which
hash value to set here; this should be the most secure hash algorithm
diff --git a/docs/attributes-registry/aws.md b/docs/attributes-registry/aws.md
index 90ca3fa8f3..88e79563d5 100644
--- a/docs/attributes-registry/aws.md
+++ b/docs/attributes-registry/aws.md
@@ -88,7 +88,7 @@ This document defines attributes for AWS Lambda.
|---|---|---|---|---|
| `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` |  |
-**[1]:** This may be different from `cloud.resource_id` if an alias is involved.
+**[1] `aws.lambda.invoked_arn`:** This may be different from `cloud.resource_id` if an alias is involved.
## Amazon Logs Attributes
@@ -101,11 +101,11 @@ This document defines attributes for AWS Logs.
| `aws.log.stream.arns` | string[] | The ARN(s) of the AWS log stream(s). [4] | `["arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:log-stream:logs/main/10838bed-421f-43ef-870a-f43feacbbb5b"]` |  |
| `aws.log.stream.names` | string[] | The name(s) of the AWS log stream(s) an application is writing to. | `["logs/main/10838bed-421f-43ef-870a-f43feacbbb5b"]` |  |
-**[2]:** See the [log group ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format).
+**[2] `aws.log.group.arns`:** See the [log group ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format).
-**[3]:** Multiple log groups must be supported for cases like multi-container applications, where a single application has sidecar containers, and each write to their own log group.
+**[3] `aws.log.group.names`:** Multiple log groups must be supported for cases like multi-container applications, where a single application has sidecar containers, and each write to their own log group.
-**[4]:** See the [log stream ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). One log group can contain several log streams, so these ARNs necessarily identify both a log group and a log stream.
+**[4] `aws.log.stream.arns`:** See the [log stream ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). One log group can contain several log streams, so these ARNs necessarily identify both a log group and a log stream.
## Amazon S3 Attributes
@@ -120,21 +120,21 @@ This document defines attributes for AWS S3.
| `aws.s3.part_number` | int | The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000. [9] | `3456` |  |
| `aws.s3.upload_id` | string | Upload ID that identifies the multipart upload. [10] | `dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ` |  |
-**[5]:** The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter.
+**[5] `aws.s3.bucket`:** The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter.
This applies to almost all S3 operations except `list-buckets`.
-**[6]:** The `copy_source` attribute applies to S3 copy operations and corresponds to the `--copy-source` parameter
+**[6] `aws.s3.copy_source`:** The `copy_source` attribute applies to S3 copy operations and corresponds to the `--copy-source` parameter
of the [copy-object operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html).
This applies in particular to the following operations:
- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html)
- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html)
-**[7]:** The `delete` attribute is only applicable to the [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) operation.
+**[7] `aws.s3.delete`:** The `delete` attribute is only applicable to the [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) operation.
The `delete` attribute corresponds to the `--delete` parameter of the
[delete-objects operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-objects.html).
-**[8]:** The `key` attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter.
+**[8] `aws.s3.key`:** The `key` attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter.
This applies in particular to the following operations:
- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html)
@@ -151,12 +151,12 @@ This applies in particular to the following operations:
- [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html)
-**[9]:** The `part_number` attribute is only applicable to the [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
+**[9] `aws.s3.part_number`:** The `part_number` attribute is only applicable to the [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
and [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) operations.
The `part_number` attribute corresponds to the `--part-number` parameter of the
[upload-part operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html).
-**[10]:** The `upload_id` attribute applies to S3 multipart-upload operations and corresponds to the `--upload-id` parameter
+**[10] `aws.s3.upload_id`:** The `upload_id` attribute applies to S3 multipart-upload operations and corresponds to the `--upload-id` parameter
of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) multipart operations.
This applies in particular to the following operations:
diff --git a/docs/attributes-registry/browser.md b/docs/attributes-registry/browser.md
index 2e16e99669..7c8829e321 100644
--- a/docs/attributes-registry/browser.md
+++ b/docs/attributes-registry/browser.md
@@ -17,11 +17,11 @@ The web browser attributes
| `browser.mobile` | boolean | A boolean that is true if the browser is running on a mobile device [3] | |  |
| `browser.platform` | string | The platform on which the browser is running [4] | `Windows`; `macOS`; `Android` |  |
-**[1]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`).
+**[1] `browser.brands`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`).
-**[2]:** This value is intended to be taken from the Navigator API `navigator.language`.
+**[2] `browser.language`:** This value is intended to be taken from the Navigator API `navigator.language`.
-**[3]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.mobile`). If unavailable, this attribute SHOULD be left unset.
+**[3] `browser.mobile`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.mobile`). If unavailable, this attribute SHOULD be left unset.
-**[4]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent.
+**[4] `browser.platform`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent.
The list of possible values is defined in the [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). Note that some (but not all) of these values can overlap with values in the [`os.type` and `os.name` attributes](./os.md). However, for consistency, the values in the `browser.platform` attribute should capture the exact value that the user agent provides.
diff --git a/docs/attributes-registry/client.md b/docs/attributes-registry/client.md
index a46409ad0a..0420cf3405 100644
--- a/docs/attributes-registry/client.md
+++ b/docs/attributes-registry/client.md
@@ -15,6 +15,6 @@ These attributes may be used to describe the client in a connection-based networ
| `client.address` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` |  |
| `client.port` | int | Client port number. [2] | `65123` |  |
-**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available.
+**[1] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available.
-**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available.
+**[2] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available.
diff --git a/docs/attributes-registry/cloud.md b/docs/attributes-registry/cloud.md
index fdaf4919e2..0a2dfd2236 100644
--- a/docs/attributes-registry/cloud.md
+++ b/docs/attributes-registry/cloud.md
@@ -19,13 +19,13 @@ A cloud environment (e.g. GCP, Azure, AWS).
| `cloud.region` | string | The geographical region the resource is running. [3] | `us-central1`; `us-east-1` |  |
| `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/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) [4] | `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/` |  |
-**[1]:** Availability zones are called "zones" on Alibaba Cloud and Google Cloud.
+**[1] `cloud.availability_zone`:** Availability zones are called "zones" on Alibaba Cloud and Google Cloud.
-**[2]:** The prefix of the service SHOULD match the one specified in `cloud.provider`.
+**[2] `cloud.platform`:** The prefix of the service SHOULD match the one specified in `cloud.provider`.
-**[3]:** 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/global-infrastructure/geographies/), [Google Cloud regions](https://cloud.google.com/about/locations), or [Tencent Cloud regions](https://www.tencentcloud.com/document/product/213/6091).
+**[3] `cloud.region`:** 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/global-infrastructure/geographies/), [Google Cloud regions](https://cloud.google.com/about/locations), or [Tencent Cloud regions](https://www.tencentcloud.com/document/product/213/6091).
-**[4]:** On some cloud providers, it may not be possible to determine the full ID at startup,
+**[4] `cloud.resource_id`:** 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.
diff --git a/docs/attributes-registry/cloudfoundry.md b/docs/attributes-registry/cloudfoundry.md
index 4253a8bf10..756b81e7a0 100644
--- a/docs/attributes-registry/cloudfoundry.md
+++ b/docs/attributes-registry/cloudfoundry.md
@@ -24,11 +24,11 @@ CloudFoundry resource attributes.
| `cloudfoundry.system.id` | string | A guid or another name describing the event source. [10] | `cf/gorouter` |  |
| `cloudfoundry.system.instance.id` | string | A guid describing the concrete instance of the event source. [11] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` |  |
-**[1]:** Application instrumentation should use the value from environment
+**[1] `cloudfoundry.app.id`:** Application instrumentation should use the value from environment
variable `VCAP_APPLICATION.application_id`. This is the same value as
reported by `cf app --guid`.
-**[2]:** CloudFoundry defines the `instance_id` in the [Loggregator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope).
+**[2] `cloudfoundry.app.instance.id`:** CloudFoundry defines the `instance_id` in the [Loggregator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope).
It is used for logs and metrics emitted by CloudFoundry. It is
supposed to contain the application instance index for applications
deployed on the runtime.
@@ -36,36 +36,36 @@ deployed on the runtime.
Application instrumentation should use the value from environment
variable `CF_INSTANCE_INDEX`.
-**[3]:** Application instrumentation should use the value from environment
+**[3] `cloudfoundry.app.name`:** Application instrumentation should use the value from environment
variable `VCAP_APPLICATION.application_name`. This is the same value
as reported by `cf apps`.
-**[4]:** Application instrumentation should use the value from environment
+**[4] `cloudfoundry.org.id`:** Application instrumentation should use the value from environment
variable `VCAP_APPLICATION.org_id`. This is the same value as
reported by `cf org --guid`.
-**[5]:** Application instrumentation should use the value from environment
+**[5] `cloudfoundry.org.name`:** Application instrumentation should use the value from environment
variable `VCAP_APPLICATION.org_name`. This is the same value as
reported by `cf orgs`.
-**[6]:** Application instrumentation should use the value from environment
+**[6] `cloudfoundry.process.id`:** Application instrumentation should use the value from environment
variable `VCAP_APPLICATION.process_id`. It is supposed to be equal to
`VCAP_APPLICATION.app_id` for applications deployed to the runtime.
For system components, this could be the actual PID.
-**[7]:** CloudFoundry applications can consist of multiple jobs. Usually the
+**[7] `cloudfoundry.process.type`:** CloudFoundry applications can consist of multiple jobs. Usually the
main process will be of type `web`. There can be additional background
tasks or side-cars with different process types.
-**[8]:** Application instrumentation should use the value from environment
+**[8] `cloudfoundry.space.id`:** Application instrumentation should use the value from environment
variable `VCAP_APPLICATION.space_id`. This is the same value as
reported by `cf space --guid`.
-**[9]:** Application instrumentation should use the value from environment
+**[9] `cloudfoundry.space.name`:** Application instrumentation should use the value from environment
variable `VCAP_APPLICATION.space_name`. This is the same value as
reported by `cf spaces`.
-**[10]:** CloudFoundry defines the `source_id` in the [Loggregator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope).
+**[10] `cloudfoundry.system.id`:** CloudFoundry defines the `source_id` in the [Loggregator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope).
It is used for logs and metrics emitted by CloudFoundry. It is
supposed to contain the component name, e.g. "gorouter", for
CloudFoundry components.
@@ -75,7 +75,7 @@ When system components are instrumented, values from the
should be used. The `system.id` should be set to
`spec.deployment/spec.name`.
-**[11]:** CloudFoundry defines the `instance_id` in the [Loggregator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope).
+**[11] `cloudfoundry.system.instance.id`:** CloudFoundry defines the `instance_id` in the [Loggregator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope).
It is used for logs and metrics emitted by CloudFoundry. It is
supposed to contain the vm id for CloudFoundry components.
diff --git a/docs/attributes-registry/container.md b/docs/attributes-registry/container.md
index 439b079184..f571b02feb 100644
--- a/docs/attributes-registry/container.md
+++ b/docs/attributes-registry/container.md
@@ -29,17 +29,17 @@ A container instance.
| `container.name` | string | Container name used by container runtime. | `opentelemetry-autoconf` |  |
| `container.runtime` | string | The container runtime managing this container. | `docker`; `containerd`; `rkt` |  |
-**[1]:** If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage.
+**[1] `container.command`:** If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage.
-**[2]:** This can sometimes be referred to as a "driver" in CSI implementations. This should represent the `name` field of the GetPluginInfo RPC.
+**[2] `container.csi.plugin.name`:** This can sometimes be referred to as a "driver" in CSI implementations. This should represent the `name` field of the GetPluginInfo RPC.
-**[3]:** This can sometimes be referred to as a "volume handle" in CSI implementations. This should represent the `Volume.volume_id` field in CSI spec.
+**[3] `container.csi.volume.id`:** This can sometimes be referred to as a "volume handle" in CSI implementations. This should represent the `Volume.volume_id` field in CSI spec.
-**[4]:** Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) endpoint.
+**[4] `container.image.id`:** Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) endpoint.
K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`.
The ID is assigned by the container runtime and can vary in different environments. Consider using `oci.manifest.digest` if it is important to identify the same image in different environments/runtimes.
-**[5]:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field.
+**[5] `container.image.repo_digests`:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field.
## Deprecated Container Attributes
diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md
index 02bb9aede5..ca43d19780 100644
--- a/docs/attributes-registry/db.md
+++ b/docs/attributes-registry/db.md
@@ -32,7 +32,7 @@ This group defines the attributes used to describe telemetry in the context of d
| `db.response.status_code` | string | Database response status code. [8] | `102`; `ORA-17002`; `08P01`; `404` |  |
| `db.system` | string | The database management system (DBMS) product as identified by the client instrumentation. [9] | `other_sql`; `adabas`; `cache` |  |
-**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
+**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
A single database query may involve multiple collections.
@@ -48,15 +48,15 @@ SHOULD NOT be captured.
This attribute has stability level RELEASE CANDIDATE.
-**[2]:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
+**[2] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system.
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
This attribute has stability level RELEASE CANDIDATE.
-**[3]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[3] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[4]:** It is RECOMMENDED to capture the value as provided by the application
+**[4] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization.
A single database query may involve multiple operations. If the operation
@@ -71,24 +71,24 @@ system specific term if more applicable.
This attribute has stability level RELEASE CANDIDATE.
-**[5]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
+**[5] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`.
This attribute has stability level RELEASE CANDIDATE.
-**[6]:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+**[6] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
-**[7]:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[7] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
-**[8]:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
+**[8] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
-**[9]:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge.
+**[9] `db.system`:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge.
This attribute has stability level RELEASE CANDIDATE.
`db.client.connection.state` 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.
@@ -225,7 +225,7 @@ This group defines attributes for Elasticsearch.
| `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` |  |
| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [10] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` |  |
-**[10]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names.
+**[10] `db.elasticsearch.path_parts`:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names.
## Deprecated Database Attributes
diff --git a/docs/attributes-registry/deployment.md b/docs/attributes-registry/deployment.md
index d687d2b880..25c3451d52 100644
--- a/docs/attributes-registry/deployment.md
+++ b/docs/attributes-registry/deployment.md
@@ -20,7 +20,7 @@ This document defines attributes for software deployments.
| `deployment.name` | string | The name of the deployment. | `deploy my app`; `deploy-frontend` |  |
| `deployment.status` | string | The status of the deployment. | `failed`; `succeeded` |  |
-**[1]:** `deployment.environment.name` does not affect the uniqueness constraints defined through
+**[1] `deployment.environment.name`:** `deployment.environment.name` does not affect the uniqueness constraints defined through
the `service.namespace`, `service.name` and `service.instance.id` resource attributes.
This implies that resources carrying the following attribute combinations MUST be
considered to be identifying the same service:
diff --git a/docs/attributes-registry/destination.md b/docs/attributes-registry/destination.md
index bf537414ab..5eac27f95c 100644
--- a/docs/attributes-registry/destination.md
+++ b/docs/attributes-registry/destination.md
@@ -15,4 +15,4 @@ These attributes may be used to describe the receiver of a network exchange/pack
| `destination.address` | string | Destination address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `destination.example.com`; `10.1.2.80`; `/tmp/my.sock` |  |
| `destination.port` | int | Destination port number | `3389`; `2888` |  |
-**[1]:** When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent the destination address behind any intermediaries, for example proxies, if it's available.
+**[1] `destination.address`:** When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent the destination address behind any intermediaries, for example proxies, if it's available.
diff --git a/docs/attributes-registry/device.md b/docs/attributes-registry/device.md
index 283cfc60a6..3d17d041e7 100644
--- a/docs/attributes-registry/device.md
+++ b/docs/attributes-registry/device.md
@@ -17,10 +17,10 @@ Describes device attributes.
| `device.model.identifier` | string | The model identifier for the device [3] | `iPhone3,4`; `SM-G920F` |  |
| `device.model.name` | string | The marketing name for the device model [4] | `iPhone 6s Plus`; `Samsung Galaxy S6` |  |
-**[1]:** The device identifier MUST only be defined using the values outlined below. This value is not an advertising identifier and MUST NOT be used as such. On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) on best practices and exact implementation details. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence.
+**[1] `device.id`:** The device identifier MUST only be defined using the values outlined below. This value is not an advertising identifier and MUST NOT be used as such. On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) on best practices and exact implementation details. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence.
-**[2]:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`.
+**[2] `device.manufacturer`:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`.
-**[3]:** It's recommended this value represents a machine-readable version of the model identifier rather than the market or consumer-friendly name of the device.
+**[3] `device.model.identifier`:** It's recommended this value represents a machine-readable version of the model identifier rather than the market or consumer-friendly name of the device.
-**[4]:** It's recommended this value represents a human-readable version of the device model rather than a machine-readable alternative.
+**[4] `device.model.name`:** It's recommended this value represents a human-readable version of the device model rather than a machine-readable alternative.
diff --git a/docs/attributes-registry/dns.md b/docs/attributes-registry/dns.md
index 52088b6e6b..b694e02b3e 100644
--- a/docs/attributes-registry/dns.md
+++ b/docs/attributes-registry/dns.md
@@ -14,4 +14,4 @@ This document defines the shared attributes used to report a DNS query.
|---|---|---|---|---|
| `dns.question.name` | string | The name being queried. [1] | `www.example.com`; `opentelemetry.io` |  |
-**[1]:** If the name field contains non-printable characters (below 32 or above 126), those characters should be represented as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. Tabs, carriage returns, and line feeds should be converted to \t, \r, and \n respectively.
+**[1] `dns.question.name`:** If the name field contains non-printable characters (below 32 or above 126), those characters should be represented as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. Tabs, carriage returns, and line feeds should be converted to \t, \r, and \n respectively.
diff --git a/docs/attributes-registry/error.md b/docs/attributes-registry/error.md
index 80e6bdba72..3867e83e66 100644
--- a/docs/attributes-registry/error.md
+++ b/docs/attributes-registry/error.md
@@ -14,7 +14,7 @@ This document defines the shared attributes used to report an error.
|---|---|---|---|---|
| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` |  |
-**[1]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
+**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
When `error.type` is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
diff --git a/docs/attributes-registry/event.md b/docs/attributes-registry/event.md
index f0856ff2e7..4489039554 100644
--- a/docs/attributes-registry/event.md
+++ b/docs/attributes-registry/event.md
@@ -14,4 +14,4 @@ Attributes for Events represented using Log Records.
|---|---|---|---|---|
| `event.name` | string | Identifies the class / type of event. [1] | `browser.mouse.click`; `device.app.lifecycle` |  |
-**[1]:** Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md). Notably, event names are namespaced to avoid collisions and provide a clean separation of semantics for events in separate domains like browser, mobile, and kubernetes.
+**[1] `event.name`:** Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md). Notably, event names are namespaced to avoid collisions and provide a clean separation of semantics for events in separate domains like browser, mobile, and kubernetes.
diff --git a/docs/attributes-registry/exception.md b/docs/attributes-registry/exception.md
index 84ad81270d..be9b732e15 100644
--- a/docs/attributes-registry/exception.md
+++ b/docs/attributes-registry/exception.md
@@ -17,7 +17,7 @@ This document defines the shared attributes used to report a single exception as
| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` |  |
| `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` |  |
-**[1]:** An exception is considered to have escaped (or left) the scope of a span,
+**[1] `exception.escaped`:** An exception is considered to have escaped (or left) the scope of a span,
if that span is ended while the exception is still logically "in flight".
This may be actually "in flight" in some languages (e.g. if the exception
is passed to a Context manager's `__exit__` method in Python) but will
diff --git a/docs/attributes-registry/faas.md b/docs/attributes-registry/faas.md
index a38c8ebffc..18d2262822 100644
--- a/docs/attributes-registry/faas.md
+++ b/docs/attributes-registry/faas.md
@@ -29,17 +29,17 @@ FaaS attributes
| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` |  |
| `faas.version` | string | The immutable version of the function being executed. [7] | `26`; `pinkfroid-00002` |  |
-**[1]:** - **AWS Lambda:** Use the (full) log stream name.
+**[1] `faas.instance`:** - **AWS Lambda:** Use the (full) log stream name.
-**[2]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function.
+**[2] `faas.invoked_name`:** SHOULD be equal to the `faas.name` resource attribute of the invoked function.
-**[3]:** SHOULD be equal to the `cloud.provider` resource attribute of the invoked function.
+**[3] `faas.invoked_provider`:** SHOULD be equal to the `cloud.provider` resource attribute of the invoked function.
-**[4]:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function.
+**[4] `faas.invoked_region`:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function.
-**[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).
+**[5] `faas.max_memory`:** 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).
-**[6]:** This is the name of the function as configured/deployed on the FaaS
+**[6] `faas.name`:** This is the name of the function as configured/deployed on the FaaS
platform and is usually different from the name of the callback
function (which may be stored in the
[`code.namespace`/`code.function`](/docs/general/attributes.md#source-code-attributes)
@@ -56,7 +56,7 @@ definition of function name MUST be used for this attribute
app can host multiple functions that would usually share
a TracerProvider (see also the `cloud.resource_id` attribute).
-**[7]:** Depending on the cloud provider and platform, use:
+**[7] `faas.version`:** 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).
diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md
index de4cd52d50..d61da8e405 100644
--- a/docs/attributes-registry/feature-flag.md
+++ b/docs/attributes-registry/feature-flag.md
@@ -24,7 +24,7 @@ This document defines attributes for Feature Flags.
| `feature_flag.variant` | string | A semantic identifier for an evaluated flag value. [1] | `red`; `true`; `on` |  |
| `feature_flag.version` | string | The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. | `1`; `01ABCDEF` |  |
-**[1]:** A semantic identifier, commonly referred to as a variant, provides a means
+**[1] `feature_flag.variant`:** A semantic identifier, commonly referred to as a variant, provides a means
for referring to a value without including the value itself. This can
provide additional context for understanding the meaning behind a value.
For example, the variant `red` maybe be used for the value `#c05543`.
diff --git a/docs/attributes-registry/file.md b/docs/attributes-registry/file.md
index 243dc8ef1f..8189d0c4d1 100644
--- a/docs/attributes-registry/file.md
+++ b/docs/attributes-registry/file.md
@@ -31,17 +31,17 @@ Describes file attributes.
| `file.size` | int | File size in bytes. | |  |
| `file.symbolic_link.target_path` | string | Path to the target of a symbolic link. [7] | `/usr/bin/python3` |  |
-**[1]:** This attribute might not be supported by some file systems — NFS, FAT32, in embedded OS, etc.
+**[1] `file.accessed`:** This attribute might not be supported by some file systems — NFS, FAT32, in embedded OS, etc.
-**[2]:** Attributes names depend on the OS or file system. Here’s a non-exhaustive list of values expected for this attribute: `archive`, `compressed`, `directory`, `encrypted`, `execute`, `hidden`, `immutable`, `journaled`, `read`, `readonly`, `symbolic link`, `system`, `temporary`, `write`.
+**[2] `file.attributes`:** Attributes names depend on the OS or file system. Here’s a non-exhaustive list of values expected for this attribute: `archive`, `compressed`, `directory`, `encrypted`, `execute`, `hidden`, `immutable`, `journaled`, `read`, `readonly`, `symbolic link`, `system`, `temporary`, `write`.
-**[3]:** `file.changed` captures the time when any of the file's properties or attributes (including the content) are changed, while `file.modified` captures the timestamp when the file content is modified.
+**[3] `file.changed`:** `file.changed` captures the time when any of the file's properties or attributes (including the content) are changed, while `file.modified` captures the timestamp when the file content is modified.
-**[4]:** This attribute might not be supported by some file systems — NFS, FAT32, in embedded OS, etc.
+**[4] `file.created`:** This attribute might not be supported by some file systems — NFS, FAT32, in embedded OS, etc.
-**[5]:** When the file name has multiple extensions (example.tar.gz), only the last one should be captured ("gz", not "tar.gz").
+**[5] `file.extension`:** When the file name has multiple extensions (example.tar.gz), only the last one should be captured ("gz", not "tar.gz").
-**[6]:** On Linux, a resource fork is used to store additional data with a filesystem object. A file always has at least one fork for the data portion, and additional forks may exist.
+**[6] `file.fork_name`:** On Linux, a resource fork is used to store additional data with a filesystem object. A file always has at least one fork for the data portion, and additional forks may exist.
On NTFS, this is analogous to an Alternate Data Stream (ADS), and the default data stream for a file is just called $DATA. Zone.Identifier is commonly used by Windows to track contents downloaded from the Internet. An ADS is typically of the form: C:\path\to\filename.extension:some_fork_name, and some_fork_name is the value that should populate `fork_name`. `filename.extension` should populate `file.name`, and `extension` should populate `file.extension`. The full path, `file.path`, will include the fork name.
-**[7]:** This attribute is only applicable to symbolic links.
+**[7] `file.symbolic_link.target_path`:** This attribute is only applicable to symbolic links.
diff --git a/docs/attributes-registry/gcp.md b/docs/attributes-registry/gcp.md
index 0ad397c713..c2788b8296 100644
--- a/docs/attributes-registry/gcp.md
+++ b/docs/attributes-registry/gcp.md
@@ -18,7 +18,7 @@ Attributes for Google Cloud client libraries.
|---|---|---|---|---|
| `gcp.client.service` | string | Identifies the Google Cloud service for which the official client library is intended. [1] | `appengine`; `run`; `firestore`; `alloydb`; `spanner` |  |
-**[1]:** Intended to be a stable identifier for Google Cloud client libraries that is uniform across implementation languages. The value should be derived from the canonical service domain for the service; for example, 'foo.googleapis.com' should result in a value of 'foo'.
+**[1] `gcp.client.service`:** Intended to be a stable identifier for Google Cloud client libraries that is uniform across implementation languages. The value should be derived from the canonical service domain for the service; for example, 'foo.googleapis.com' should result in a value of 'foo'.
## GCP - Google Cloud Run Attributes
diff --git a/docs/attributes-registry/gen-ai.md b/docs/attributes-registry/gen-ai.md
index 1381a437be..c89c711244 100644
--- a/docs/attributes-registry/gen-ai.md
+++ b/docs/attributes-registry/gen-ai.md
@@ -33,9 +33,9 @@ This document defines the attributes used to describe telemetry in the context o
| `gen_ai.usage.input_tokens` | int | The number of tokens used in the GenAI input (prompt). | `100` |  |
| `gen_ai.usage.output_tokens` | int | The number of tokens used in the GenAI response (completion). | `180` |  |
-**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
+**[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
-**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified
+**[2] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified
by `gen_ai.request.model` and `gen_ai.response.model` attributes.
The actual GenAI product may differ from the one identified by the client.
diff --git a/docs/attributes-registry/graphql.md b/docs/attributes-registry/graphql.md
index 1b08f50c53..81891eab73 100644
--- a/docs/attributes-registry/graphql.md
+++ b/docs/attributes-registry/graphql.md
@@ -16,7 +16,7 @@ This document defines attributes for GraphQL.
| `graphql.operation.name` | string | The name of the operation being executed. | `findBookById` |  |
| `graphql.operation.type` | string | The type of the operation being executed. | `query`; `mutation`; `subscription` |  |
-**[1]:** The value may be sanitized to exclude sensitive information.
+**[1] `graphql.document`:** The value may be sanitized to exclude sensitive information.
`graphql.operation.type` 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/docs/attributes-registry/hardware.md b/docs/attributes-registry/hardware.md
index 45b5a2d1f3..443aea784a 100644
--- a/docs/attributes-registry/hardware.md
+++ b/docs/attributes-registry/hardware.md
@@ -18,7 +18,7 @@ Attributes for hardware.
| `hw.state` | string | The current state of the component | `ok`; `degraded`; `failed` |  |
| `hw.type` | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` |  |
-**[1]:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`.
+**[1] `hw.type`:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`.
`hw.state` 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/docs/attributes-registry/host.md b/docs/attributes-registry/host.md
index f3cec69aae..4a21ab9b3a 100644
--- a/docs/attributes-registry/host.md
+++ b/docs/attributes-registry/host.md
@@ -28,11 +28,11 @@ A host is defined as a computing instance. For example, physical servers, virtua
| `host.name` | string | Name of the host. On Unix systems, it may contain what the hostname command returns, or the fully qualified hostname, or another name specified by the user. | `opentelemetry-test` |  |
| `host.type` | string | Type of host. For Cloud, this must be the machine type. | `n1-standard-1` |  |
-**[1]:** [CPUID](https://wiki.osdev.org/CPUID) command returns the vendor ID string in EBX, EDX and ECX registers. Writing these to memory in this order results in a 12-character string.
+**[1] `host.cpu.vendor.id`:** [CPUID](https://wiki.osdev.org/CPUID) command returns the vendor ID string in EBX, EDX and ECX registers. Writing these to memory in this order results in a 12-character string.
-**[2]:** IPv4 Addresses MUST be specified in dotted-quad notation. IPv6 addresses MUST be specified in the [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952.html) format.
+**[2] `host.ip`:** IPv4 Addresses MUST be specified in dotted-quad notation. IPv6 addresses MUST be specified in the [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952.html) format.
-**[3]:** MAC Addresses MUST be represented in [IEEE RA hexadecimal form](https://standards.ieee.org/wp-content/uploads/import/documents/tutorials/eui.pdf): as hyphen-separated octets in uppercase hexadecimal form from most to least significant.
+**[3] `host.mac`:** MAC Addresses MUST be represented in [IEEE RA hexadecimal form](https://standards.ieee.org/wp-content/uploads/import/documents/tutorials/eui.pdf): as hyphen-separated octets in uppercase hexadecimal form from most to least significant.
`host.arch` 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/docs/attributes-registry/http.md b/docs/attributes-registry/http.md
index 57953b39be..2d9e83ddff 100644
--- a/docs/attributes-registry/http.md
+++ b/docs/attributes-registry/http.md
@@ -28,11 +28,11 @@ This document defines semantic convention attributes in the HTTP namespace.
| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` |  |
| `http.route` | string | The matched route, that is, the path template in the format used by the respective server framework. [5] | `/users/:userID?`; `{controller}/{action}/{id?}` |  |
-**[1]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
+**[1] `http.request.header`:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
The `User-Agent` header is already captured in the `user_agent.original` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended.
The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers.
-**[2]:** HTTP request method value SHOULD be "known" to the instrumentation.
+**[2] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@@ -47,13 +47,13 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
-**[3]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other).
+**[3] `http.request.resend_count`:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other).
-**[4]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
+**[4] `http.response.header`:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
Users MAY explicitly configure instrumentations to capture them even though it is not recommended.
The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers.
-**[5]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
+**[5] `http.route`:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
`http.connection.state` 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/docs/attributes-registry/ios.md b/docs/attributes-registry/ios.md
index a847e932eb..784abe1e98 100644
--- a/docs/attributes-registry/ios.md
+++ b/docs/attributes-registry/ios.md
@@ -14,7 +14,7 @@ The iOS platform on which the iOS application is running.
|---|---|---|---|---|
| `ios.state` | string | Deprecated use the `device.app.lifecycle` event definition including `ios.state` as a payload field instead. [1] | `active`; `inactive`; `background` | 
Moved to a payload field of `device.app.lifecycle`. |
-**[1]:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived.
+**[1] `ios.state`:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived.
`ios.state` 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/docs/attributes-registry/jvm.md b/docs/attributes-registry/jvm.md
index 8a3d4e459c..a503c44343 100644
--- a/docs/attributes-registry/jvm.md
+++ b/docs/attributes-registry/jvm.md
@@ -20,13 +20,13 @@ This document defines Java Virtual machine related attributes.
| `jvm.thread.daemon` | boolean | Whether the thread is daemon or not. | |  |
| `jvm.thread.state` | string | State of the thread. | `runnable`; `blocked` |  |
-**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()).
+**[1] `jvm.buffer.pool.name`:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()).
-**[2]:** Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()).
+**[2] `jvm.gc.action`:** Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()).
-**[3]:** Garbage collector name is generally obtained via [GarbageCollectionNotificationInfo#getGcName()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcName()).
+**[3] `jvm.gc.name`:** Garbage collector name is generally obtained via [GarbageCollectionNotificationInfo#getGcName()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcName()).
-**[4]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
+**[4] `jvm.memory.pool.name`:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
`jvm.memory.type` 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/docs/attributes-registry/k8s.md b/docs/attributes-registry/k8s.md
index dcda4ed00a..f62a09ec5f 100644
--- a/docs/attributes-registry/k8s.md
+++ b/docs/attributes-registry/k8s.md
@@ -42,7 +42,7 @@ Kubernetes resource attributes.
| `k8s.volume.name` | string | The name of the K8s volume. | `volume0` |  |
| `k8s.volume.type` | string | The type of the K8s volume. | `emptyDir`; `persistentVolumeClaim` |  |
-**[1]:** K8s doesn't have support for obtaining a cluster ID. If this is ever
+**[1] `k8s.cluster.uid`:** K8s doesn't have support for obtaining a cluster ID. If this is ever
added, we will recommend collecting the `k8s.cluster.uid` through the
official APIs. In the meantime, we are able to use the `uid` of the
`kube-system` namespace as a proxy for cluster ID. Read on for the
diff --git a/docs/attributes-registry/log.md b/docs/attributes-registry/log.md
index 5371589ccf..c6ebd18ba7 100644
--- a/docs/attributes-registry/log.md
+++ b/docs/attributes-registry/log.md
@@ -45,7 +45,7 @@ This document defines the generic attributes that may be used in any Log Record.
| `log.record.original` | string | The complete original Log Record. [1] | `77 <86>1 2015-08-06T21:58:59.694Z 192.168.2.133 inactive - - - Something happened`; `[INFO] 8/3/24 12:34:56 Something happened` |  |
| `log.record.uid` | string | A unique identifier for the Log Record. [2] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` |  |
-**[1]:** This value MAY be added when processing a Log Record which was originally transmitted as a string or equivalent data type AND the Body field of the Log Record does not contain the same value. (e.g. a syslog or a log record read from a file.)
+**[1] `log.record.original`:** This value MAY be added when processing a Log Record which was originally transmitted as a string or equivalent data type AND the Body field of the Log Record does not contain the same value. (e.g. a syslog or a log record read from a file.)
-**[2]:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values.
+**[2] `log.record.uid`:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values.
The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), but other identifiers (e.g. UUID) may be used as needed.
diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md
index f199868334..ed78f163be 100644
--- a/docs/attributes-registry/messaging.md
+++ b/docs/attributes-registry/messaging.md
@@ -38,26 +38,26 @@ Attributes describing telemetry around messaging systems and messaging activitie
| `messaging.operation.type` | string | A string identifying the type of the messaging operation. [8] | `create`; `send`; `receive` |  |
| `messaging.system` | string | The messaging system as identified by the client instrumentation. [9] | `activemq`; `aws_sqs`; `eventgrid` |  |
-**[1]:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
+**[1] `messaging.batch.message_count`:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
-**[2]:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.consumer.group.name` is applicable and what it means in the context of that system.
+**[2] `messaging.consumer.group.name`:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.consumer.group.name` is applicable and what it means in the context of that system.
-**[3]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
+**[3] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
-**[4]:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.destination.subscription.name` is applicable and what it means in the context of that system.
+**[4] `messaging.destination.subscription.name`:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.destination.subscription.name` is applicable and what it means in the context of that system.
-**[5]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation.
+**[5] `messaging.destination.template`:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation.
-**[6]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed
+**[6] `messaging.message.body.size`:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed
body size should be used.
-**[7]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed
+**[7] `messaging.message.envelope.size`:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed
size should be used.
-**[8]:** If a custom value is used, it MUST be of low cardinality.
+**[8] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality.
-**[9]:** The actual messaging system may differ from the one known by the client. For example, when using Kafka client libraries to communicate with Azure Event Hubs, the `messaging.system` is set to `kafka` based on the instrumentation's best knowledge.
+**[9] `messaging.system`:** The actual messaging system may differ from the one known by the client. For example, when using Kafka client libraries to communicate with Azure Event Hubs, the `messaging.system` is set to `kafka` based on the instrumentation's best knowledge.
`messaging.operation.type` 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.
@@ -116,7 +116,7 @@ This group describes attributes specific to Apache Kafka.
| `messaging.kafka.message.tombstone` | boolean | A boolean that is true if the message is a tombstone. | |  |
| `messaging.kafka.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` |  |
-**[10]:** If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value.
+**[10] `messaging.kafka.message.key`:** If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value.
## RabbitMQ Attributes
diff --git a/docs/attributes-registry/network.md b/docs/attributes-registry/network.md
index a6c97b8cb2..ff9bec8852 100644
--- a/docs/attributes-registry/network.md
+++ b/docs/attributes-registry/network.md
@@ -32,17 +32,17 @@ These attributes may be used for any network related operation.
| `network.transport` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` |  |
| `network.type` | string | [OSI network layer](https://wikipedia.org/wiki/Network_layer) or non-OSI equivalent. [4] | `ipv4`; `ipv6` |  |
-**[1]:** The value SHOULD be normalized to lowercase.
+**[1] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
-**[2]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
+**[2] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
-**[3]:** The value SHOULD be normalized to lowercase.
+**[3] `network.transport`:** The value SHOULD be normalized to lowercase.
Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport. For example
different processes could be listening on TCP port 12345 and UDP port 12345.
-**[4]:** The value SHOULD be normalized to lowercase.
+**[4] `network.type`:** The value SHOULD be normalized to lowercase.
`network.connection.subtype` 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/docs/attributes-registry/oci.md b/docs/attributes-registry/oci.md
index 5674fa08db..6c8aa38553 100644
--- a/docs/attributes-registry/oci.md
+++ b/docs/attributes-registry/oci.md
@@ -14,5 +14,5 @@ An OCI image manifest.
|---|---|---|---|---|
| `oci.manifest.digest` | string | The digest of the OCI image manifest. For container images specifically is the digest by which the container image is known. [1] | `sha256:e4ca62c0d62f3e886e684806dfe9d4e0cda60d54986898173c1083856cfda0f4` |  |
-**[1]:** Follows [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md), and specifically the [Digest property](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests).
+**[1] `oci.manifest.digest`:** Follows [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md), and specifically the [Digest property](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests).
An example can be found in [Example Image Manifest](https://docs.docker.com/registry/spec/manifest-v2-2/#example-image-manifest).
diff --git a/docs/attributes-registry/opentracing.md b/docs/attributes-registry/opentracing.md
index ce73840fcd..ec1deb4087 100644
--- a/docs/attributes-registry/opentracing.md
+++ b/docs/attributes-registry/opentracing.md
@@ -14,7 +14,7 @@ Attributes used by the OpenTracing Shim layer.
|---|---|---|---|---|
| `opentracing.ref_type` | string | Parent-child Reference type [1] | `child_of`; `follows_from` |  |
-**[1]:** The causal relationship between a child Span and a parent Span.
+**[1] `opentracing.ref_type`:** The causal relationship between a child Span and a parent Span.
`opentracing.ref_type` 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/docs/attributes-registry/process.md b/docs/attributes-registry/process.md
index 19f60d94b6..d03020506f 100644
--- a/docs/attributes-registry/process.md
+++ b/docs/attributes-registry/process.md
@@ -48,11 +48,11 @@ An operating system process.
| `process.vpid` | int | Virtual process identifier. [3] | `12` |  |
| `process.working_directory` | string | The working directory of the process. | `/root` |  |
-**[1]:** This field can be useful for querying or performing bucket analysis on how many arguments were provided to start a process. More arguments may be an indication of suspicious activity.
+**[1] `process.args_count`:** This field can be useful for querying or performing bucket analysis on how many arguments were provided to start a process. More arguments may be an indication of suspicious activity.
-**[2]:** In many Unix-like systems, process title (proctitle), is the string that represents the name or command line of a running process, displayed by system monitoring tools like ps, top, and htop.
+**[2] `process.title`:** In many Unix-like systems, process title (proctitle), is the string that represents the name or command line of a running process, displayed by system monitoring tools like ps, top, and htop.
-**[3]:** The process ID within a PID namespace. This is not necessarily unique across all processes on the host but it is unique within the process namespace that the process exists within.
+**[3] `process.vpid`:** The process ID within a PID namespace. This is not necessarily unique across all processes on the host but it is unique within the process namespace that the process exists within.
`process.context_switch_type` 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/docs/attributes-registry/rpc.md b/docs/attributes-registry/rpc.md
index 2dc4810d0b..1639adb68e 100644
--- a/docs/attributes-registry/rpc.md
+++ b/docs/attributes-registry/rpc.md
@@ -33,19 +33,19 @@ This document defines attributes for remote procedure calls.
| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [7] | `myservice.EchoService` |  |
| `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc`; `java_rmi`; `dotnet_wcf` |  |
-**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
+**[1] `rpc.connect_rpc.request.metadata`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
-**[2]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
+**[2] `rpc.connect_rpc.response.metadata`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
-**[3]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
+**[3] `rpc.grpc.request.metadata`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
-**[4]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
+**[4] `rpc.grpc.response.metadata`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
-**[5]:** This way we guarantee that the values will be consistent between different implementations.
+**[5] `rpc.message.id`:** This way we guarantee that the values will be consistent between different implementations.
-**[6]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[6] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[7]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[7] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`rpc.connect_rpc.error_code` 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/docs/attributes-registry/server.md b/docs/attributes-registry/server.md
index 7ea59e0cdc..6f451850bb 100644
--- a/docs/attributes-registry/server.md
+++ b/docs/attributes-registry/server.md
@@ -15,6 +15,6 @@ These attributes may be used to describe the server in a connection-based networ
| `server.address` | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` |  |
| `server.port` | int | Server port number. [2] | `80`; `8080`; `443` |  |
-**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[1] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[2] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
diff --git a/docs/attributes-registry/service.md b/docs/attributes-registry/service.md
index 6330270636..e922f57799 100644
--- a/docs/attributes-registry/service.md
+++ b/docs/attributes-registry/service.md
@@ -17,7 +17,7 @@ A service instance.
| `service.namespace` | string | A namespace for `service.name`. [3] | `Shop` |  |
| `service.version` | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` |  |
-**[1]:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words
+**[1] `service.instance.id`:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words
`service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to
distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled
service).
@@ -44,6 +44,6 @@ However, Collectors can set the `service.instance.id` if they can unambiguously
for that telemetry. This is typically the case for scraping receivers, as they know the target address and
port.
-**[2]:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`.
+**[2] `service.name`:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`.
-**[3]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace.
+**[3] `service.namespace`:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace.
diff --git a/docs/attributes-registry/source.md b/docs/attributes-registry/source.md
index 5ee20afb67..5d6147558b 100644
--- a/docs/attributes-registry/source.md
+++ b/docs/attributes-registry/source.md
@@ -15,4 +15,4 @@ These attributes may be used to describe the sender of a network exchange/packet
| `source.address` | string | Source address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `source.example.com`; `10.1.2.80`; `/tmp/my.sock` |  |
| `source.port` | int | Source port number | `3389`; `2888` |  |
-**[1]:** When observed from the destination side, and when communicating through an intermediary, `source.address` SHOULD represent the source address behind any intermediaries, for example proxies, if it's available.
+**[1] `source.address`:** When observed from the destination side, and when communicating through an intermediary, `source.address` SHOULD represent the source address behind any intermediaries, for example proxies, if it's available.
diff --git a/docs/attributes-registry/telemetry.md b/docs/attributes-registry/telemetry.md
index 39d1a8de55..6d619bbdb8 100644
--- a/docs/attributes-registry/telemetry.md
+++ b/docs/attributes-registry/telemetry.md
@@ -18,10 +18,10 @@ This document defines attributes for telemetry SDK.
| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [2] | `opentelemetry` |  |
| `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` |  |
-**[1]:** Official auto instrumentation agents and distributions SHOULD set the `telemetry.distro.name` attribute to
+**[1] `telemetry.distro.name`:** Official auto instrumentation agents and distributions SHOULD set the `telemetry.distro.name` attribute to
a string starting with `opentelemetry-`, e.g. `opentelemetry-java-instrumentation`.
-**[2]:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`.
+**[2] `telemetry.sdk.name`:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`.
If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the
`telemetry.sdk.name` attribute to the fully-qualified class or module name of this SDK's main entry point
or another suitable identifier depending on the language.
diff --git a/docs/attributes-registry/tls.md b/docs/attributes-registry/tls.md
index 2002a76972..7465c25a96 100644
--- a/docs/attributes-registry/tls.md
+++ b/docs/attributes-registry/tls.md
@@ -44,7 +44,7 @@ This document defines semantic convention attributes in the TLS namespace.
| `tls.server.not_before` | string | Date/Time indicating when server certificate is first considered valid. | `1970-01-01T00:00:00.000Z` |  |
| `tls.server.subject` | string | Distinguished name of subject of the x.509 certificate presented by the server. | `CN=myserver, OU=Documentation Team, DC=example, DC=com` |  |
-**[1]:** The values allowed for `tls.cipher` MUST be one of the `Descriptions` of the [registered TLS Cipher Suits](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#table-tls-parameters-4).
+**[1] `tls.cipher`:** The values allowed for `tls.cipher` MUST be one of the `Descriptions` of the [registered TLS Cipher Suits](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#table-tls-parameters-4).
`tls.protocol.name` 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/docs/attributes-registry/url.md b/docs/attributes-registry/url.md
index 740bcfd7b1..963184f19c 100644
--- a/docs/attributes-registry/url.md
+++ b/docs/attributes-registry/url.md
@@ -26,11 +26,11 @@ Attributes describing URL.
| `url.template` | string | The low-cardinality template of an [absolute path reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.2). | `/users/{id}`; `/users/:id`; `/users?id={id}` |  |
| `url.top_level_domain` | string | The effective top level domain (eTLD), also known as the domain suffix, is the last part of the domain name. For example, the top level domain for example.com is `com`. [9] | `com`; `co.uk` |  |
-**[1]:** In some cases a URL may refer to an IP and/or port directly, without a domain name. In this case, the IP address would go to the domain field. If the URL contains a [literal IPv6 address](https://www.rfc-editor.org/rfc/rfc2732#section-2) enclosed by `[` and `]`, the `[` and `]` characters should also be captured in the domain field.
+**[1] `url.domain`:** In some cases a URL may refer to an IP and/or port directly, without a domain name. In this case, the IP address would go to the domain field. If the URL contains a [literal IPv6 address](https://www.rfc-editor.org/rfc/rfc2732#section-2) enclosed by `[` and `]`, the `[` and `]` characters should also be captured in the domain field.
-**[2]:** The file extension is only set if it exists, as not every url has a file extension. When the file name has multiple extensions `example.tar.gz`, only the last one should be captured `gz`, not `tar.gz`.
+**[2] `url.extension`:** The file extension is only set if it exists, as not every url has a file extension. When the file name has multiple extensions `example.tar.gz`, only the last one should be captured `gz`, not `tar.gz`.
-**[3]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment
+**[3] `url.full`:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment
is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless.
`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`.
@@ -54,12 +54,12 @@ This list is subject to change over time.
When a query string value is redacted, the query string key SHOULD still be preserved, e.g.
`https://www.example.com/path?color=blue&sig=REDACTED`.
-**[4]:** In network monitoring, the observed URL may be a full URL, whereas in access logs, the URL is often just represented as a path. This field is meant to represent the URL as it was observed, complete or not.
+**[4] `url.original`:** In network monitoring, the observed URL may be a full URL, whereas in access logs, the URL is often just represented as a path. This field is meant to represent the URL as it was observed, complete or not.
`url.original` might contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case password and username SHOULD NOT be redacted and attribute's value SHOULD remain the same.
-**[5]:** Sensitive content provided in `url.path` SHOULD be scrubbed when instrumentations can identify it.
+**[5] `url.path`:** Sensitive content provided in `url.path` SHOULD be scrubbed when instrumentations can identify it.
-**[6]:** Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it.
+**[6] `url.query`:** Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it.
Query string values for the following keys SHOULD be redacted by default and replaced by the value `REDACTED`:
@@ -74,8 +74,8 @@ This list is subject to change over time.
When a query string value is redacted, the query string key SHOULD still be preserved, e.g.
`q=OpenTelemetry&sig=REDACTED`.
-**[7]:** This value can be determined precisely with the [public suffix list](http://publicsuffix.org). For example, the registered domain for `foo.example.com` is `example.com`. Trying to approximate this by simply taking the last two labels will not work well for TLDs such as `co.uk`.
+**[7] `url.registered_domain`:** This value can be determined precisely with the [public suffix list](http://publicsuffix.org). For example, the registered domain for `foo.example.com` is `example.com`. Trying to approximate this by simply taking the last two labels will not work well for TLDs such as `co.uk`.
-**[8]:** The subdomain portion of `www.east.mydomain.co.uk` is `east`. If the domain has multiple levels of subdomain, such as `sub2.sub1.example.com`, the subdomain field should contain `sub2.sub1`, with no trailing period.
+**[8] `url.subdomain`:** The subdomain portion of `www.east.mydomain.co.uk` is `east`. If the domain has multiple levels of subdomain, such as `sub2.sub1.example.com`, the subdomain field should contain `sub2.sub1`, with no trailing period.
-**[9]:** This value can be determined precisely with the [public suffix list](http://publicsuffix.org).
+**[9] `url.top_level_domain`:** This value can be determined precisely with the [public suffix list](http://publicsuffix.org).
diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md
index 6afe7b8549..37be97223f 100644
--- a/docs/attributes-registry/user-agent.md
+++ b/docs/attributes-registry/user-agent.md
@@ -16,6 +16,6 @@ Describes user-agent attributes.
| `user_agent.original` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1`; `YourApp/1.0.0 grpc-java-okhttp/1.27.2` |  |
| `user_agent.version` | string | Version of the user-agent extracted from original. Usually refers to the browser's version [2] | `14.1.2`; `1.0.0` |  |
-**[1]:** [Example](https://www.whatsmyua.info) of extracting browser's name from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant name SHOULD be selected. In such a scenario it should align with `user_agent.version`
+**[1] `user_agent.name`:** [Example](https://www.whatsmyua.info) of extracting browser's name from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant name SHOULD be selected. In such a scenario it should align with `user_agent.version`
-**[2]:** [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant version SHOULD be selected. In such a scenario it should align with `user_agent.name`
+**[2] `user_agent.version`:** [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant version SHOULD be selected. In such a scenario it should align with `user_agent.name`
diff --git a/docs/attributes-registry/user.md b/docs/attributes-registry/user.md
index 0f061b55ac..e347e700d9 100644
--- a/docs/attributes-registry/user.md
+++ b/docs/attributes-registry/user.md
@@ -19,4 +19,4 @@ Describes information about the user.
| `user.name` | string | Short name or login/username of the user. | `a.einstein` |  |
| `user.roles` | string[] | Array of user roles at the time of the event. | `["admin", "reporting_user"]` |  |
-**[1]:** Useful if `user.id` or `user.name` contain confidential information and cannot be used.
+**[1] `user.hash`:** Useful if `user.id` or `user.name` contain confidential information and cannot be used.
diff --git a/docs/attributes-registry/v8js.md b/docs/attributes-registry/v8js.md
index 3ca30207c9..bb1ca488f3 100644
--- a/docs/attributes-registry/v8js.md
+++ b/docs/attributes-registry/v8js.md
@@ -15,7 +15,7 @@ Describes V8 JS Engine Runtime related attributes.
| `v8js.gc.type` | string | The type of garbage collection. | `major`; `minor`; `incremental` |  |
| `v8js.heap.space.name` | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` |  |
-**[1]:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics)
+**[1] `v8js.heap.space.name`:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics)
`v8js.gc.type` 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/docs/attributes-registry/vcs.md b/docs/attributes-registry/vcs.md
index 15fc8f3f4e..d77403dc69 100644
--- a/docs/attributes-registry/vcs.md
+++ b/docs/attributes-registry/vcs.md
@@ -29,7 +29,7 @@ This group defines the attributes for [Version Control Systems (VCS)](https://wi
| `vcs.repository.url.full` | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` |  |
| `vcs.revision_delta.direction` | string | The type of revision comparison. | `ahead`; `behind` |  |
-**[1]:** The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf),
+**[1] `vcs.ref.base.revision`:** The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf),
of the recorded change to a ref within a repository pointing to a
commit [commit](https://git-scm.com/docs/git-commit) object. It does
not necessarily have to be a hash; it can simply define a
@@ -39,7 +39,7 @@ it is identical to the `ref.base.name`, it SHOULD still be included. It is
up to the implementer to decide which value to set as the revision
based on the VCS system and situational context.
-**[2]:** The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf),
+**[2] `vcs.ref.head.revision`:** The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf),
of the recorded change to a ref within a repository pointing to a
commit [commit](https://git-scm.com/docs/git-commit) object. It does
not necessarily have to be a hash; it can simply define a
diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md
index 84b936b71d..b532fae2d9 100644
--- a/docs/cloud-providers/aws-sdk.md
+++ b/docs/cloud-providers/aws-sdk.md
@@ -38,9 +38,9 @@ with the naming guidelines for RPC client spans.
| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` |  |
| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` |  |
-**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[1] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`rpc.system` 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/docs/database/cassandra.md b/docs/database/cassandra.md
index 456d6cad79..7d93e91b1a 100644
--- a/docs/database/cassandra.md
+++ b/docs/database/cassandra.md
@@ -42,7 +42,7 @@ The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend a
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [17] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [18] | `someval`; `55` | `Opt-In` |  |
-**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
+**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
A single database query may involve multiple collections.
@@ -60,12 +60,12 @@ This attribute has stability level RELEASE CANDIDATE.
**[2]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
-**[3]:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
+**[3] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system.
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
This attribute has stability level RELEASE CANDIDATE.
-**[4]:** It is RECOMMENDED to capture the value as provided by the application
+**[4] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization.
A single database query may involve multiple operations. If the operation
@@ -82,30 +82,30 @@ This attribute has stability level RELEASE CANDIDATE.
**[5]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-**[6]:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
+**[6] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
**[7]:** If the operation failed and status code is available.
-**[8]:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[8] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[9]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[9] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[10]:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[11]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[11] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[12]:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+**[12] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[13]:** if readily available or if instrumentation supports query summarization.
-**[14]:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[14] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
@@ -113,11 +113,11 @@ This attribute has stability level RELEASE CANDIDATE.
**[15]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
-**[16]:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
+**[16] `network.peer.address`:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
-**[17]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[17] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[18]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
+**[18] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`.
This attribute has stability level RELEASE CANDIDATE.
diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md
index 6e0781ecb1..1662719b38 100644
--- a/docs/database/cosmosdb.md
+++ b/docs/database/cosmosdb.md
@@ -60,11 +60,11 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net
| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [15] | `cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|` | `Recommended` |  |
| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` |  |
-**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
+**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
**[2]:** if not `gateway` (the default value is assumed to be `gateway`).
-**[3]:** The `db.operation.name` has the following list of well-known values.
+**[3] `db.operation.name`:** The `db.operation.name` has the following list of well-known values.
If one of them applies, then the respective value MUST be used.
Batch operations:
@@ -190,28 +190,28 @@ additional values when introducing new operations.
**[4]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-**[5]:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
+**[5] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
-**[6]:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[6] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[8]:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.DocumentDB` for all operations performed by Cosmos DB client.
+**[8] `az.namespace`:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.DocumentDB` for all operations performed by Cosmos DB client.
-**[9]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[9] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[10]:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+**[10] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[11]:** if readily available or if instrumentation supports query summarization.
-**[12]:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[12] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
@@ -219,13 +219,13 @@ This attribute has stability level RELEASE CANDIDATE.
**[13]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
-**[14]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[14] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[15]:** The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled.
+**[15] `user_agent.original`:** The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled.
Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it).
Default value is "NS".
-**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
+**[16] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`.
This attribute has stability level RELEASE CANDIDATE.
@@ -346,9 +346,9 @@ Explaining bucket configuration:
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Conditionally Required` [8] |  |
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
+**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-**[2]:** It is RECOMMENDED to capture the value as provided by the application
+**[2] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization.
A single database query may involve multiple operations. If the operation
@@ -365,21 +365,21 @@ This attribute has stability level RELEASE CANDIDATE.
**[3]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-**[4]:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
+**[4] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
**[5]:** If the operation failed and status code is available.
-**[6]:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[6] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[8]:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[9]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[9] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
`db.cosmosdb.consistency_level` 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.
@@ -424,11 +424,11 @@ It captures the number of active instances at any given time. Best practices dic
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [1] | `80`; `8080`; `443` | `Conditionally Required` [2] |  |
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-**[1]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[1] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[2]:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[3] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md
index 2d5ba06070..d103d6b147 100644
--- a/docs/database/couchdb.md
+++ b/docs/database/couchdb.md
@@ -29,26 +29,26 @@ The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and o
| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [7] | `2`; `3`; `4` | `Recommended` |  |
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-**[1]:** In **CouchDB**, `db.operation.name` should be set to the HTTP method + the target REST route according to the API reference documentation. For example, when retrieving a document, `db.operation.name` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`](https://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid).
+**[1] `db.operation.name`:** In **CouchDB**, `db.operation.name` should be set to the HTTP method + the target REST route according to the API reference documentation. For example, when retrieving a document, `db.operation.name` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`](https://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid).
-**[2]:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
+**[2] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
**[3]:** If response was received and the HTTP response code is available.
-**[4]:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[4] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[5]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[5] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[6]:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[7]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[7] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[8]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[8] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
The following attributes can be important for making sampling decisions
and SHOULD be provided **at span creation time** (if provided at all):
diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md
index 145dff3c29..bcddca7eb3 100644
--- a/docs/database/database-metrics.md
+++ b/docs/database/database-metrics.md
@@ -96,10 +96,10 @@ of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`.
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [16] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Opt-In` |  |
-**[1]:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge.
+**[1] `db.system`:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge.
This attribute has stability level RELEASE CANDIDATE.
-**[2]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
+**[2] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
A single database query may involve multiple collections.
@@ -117,12 +117,12 @@ This attribute has stability level RELEASE CANDIDATE.
**[3]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
-**[4]:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
+**[4] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system.
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
This attribute has stability level RELEASE CANDIDATE.
-**[5]:** It is RECOMMENDED to capture the value as provided by the application
+**[5] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization.
A single database query may involve multiple operations. If the operation
@@ -139,32 +139,32 @@ This attribute has stability level RELEASE CANDIDATE.
**[6]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-**[7]:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
+**[7] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
**[8]:** If the operation failed and status code is available.
-**[9]:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[9] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[10]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[10] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[11]:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[12]:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+**[12] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[13]:** if readily available or if instrumentation supports query summarization.
-**[14]:** Semantic conventions for individual database systems SHOULD document whether `network.peer.*` attributes are applicable. Network peer address and port are useful when the application interacts with individual database nodes directly.
+**[14] `network.peer.address`:** Semantic conventions for individual database systems SHOULD document whether `network.peer.*` attributes are applicable. Network peer address and port are useful when the application interacts with individual database nodes directly.
If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
-**[15]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[16]:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[16] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
@@ -281,10 +281,10 @@ Explaining bucket configuration:
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [16] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Opt-In` |  |
-**[1]:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge.
+**[1] `db.system`:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge.
This attribute has stability level RELEASE CANDIDATE.
-**[2]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
+**[2] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
A single database query may involve multiple collections.
@@ -302,12 +302,12 @@ This attribute has stability level RELEASE CANDIDATE.
**[3]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
-**[4]:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
+**[4] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system.
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
This attribute has stability level RELEASE CANDIDATE.
-**[5]:** It is RECOMMENDED to capture the value as provided by the application
+**[5] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization.
A single database query may involve multiple operations. If the operation
@@ -324,32 +324,32 @@ This attribute has stability level RELEASE CANDIDATE.
**[6]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-**[7]:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
+**[7] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
**[8]:** If the operation failed and status code is available.
-**[9]:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[9] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[10]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[10] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[11]:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[12]:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+**[12] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[13]:** if readily available or if instrumentation supports query summarization.
-**[14]:** Semantic conventions for individual database systems SHOULD document whether `network.peer.*` attributes are applicable. Network peer address and port are useful when the application interacts with individual database nodes directly.
+**[14] `network.peer.address`:** Semantic conventions for individual database systems SHOULD document whether `network.peer.*` attributes are applicable. Network peer address and port are useful when the application interacts with individual database nodes directly.
If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
-**[15]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[16]:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[16] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md
index 15c27c725e..b7bda1fe06 100644
--- a/docs/database/database-spans.md
+++ b/docs/database/database-spans.md
@@ -114,10 +114,10 @@ These attributes will usually be the same for all operations performed over the
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [18] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [19] | `someval`; `55` | `Opt-In` |  |
-**[1]:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge.
+**[1] `db.system`:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge.
This attribute has stability level RELEASE CANDIDATE.
-**[2]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
+**[2] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
A single database query may involve multiple collections.
@@ -135,12 +135,12 @@ This attribute has stability level RELEASE CANDIDATE.
**[3]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
-**[4]:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
+**[4] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system.
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
This attribute has stability level RELEASE CANDIDATE.
-**[5]:** It is RECOMMENDED to capture the value as provided by the application
+**[5] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization.
A single database query may involve multiple operations. If the operation
@@ -157,30 +157,30 @@ This attribute has stability level RELEASE CANDIDATE.
**[6]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-**[7]:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
+**[7] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
**[8]:** If the operation failed and status code is available.
-**[9]:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[9] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[10]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[10] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[11]:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[12]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[12] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[13]:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+**[13] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[14]:** if readily available or if instrumentation supports query summarization.
-**[15]:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[15] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
@@ -188,12 +188,12 @@ This attribute has stability level RELEASE CANDIDATE.
**[16]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
-**[17]:** Semantic conventions for individual database systems SHOULD document whether `network.peer.*` attributes are applicable. Network peer address and port are useful when the application interacts with individual database nodes directly.
+**[17] `network.peer.address`:** Semantic conventions for individual database systems SHOULD document whether `network.peer.*` attributes are applicable. Network peer address and port are useful when the application interacts with individual database nodes directly.
If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
-**[18]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[18] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[19]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
+**[19] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`.
This attribute has stability level RELEASE CANDIDATE.
diff --git a/docs/database/dynamodb.md b/docs/database/dynamodb.md
index 5c55d6ce8c..30f4d496b3 100644
--- a/docs/database/dynamodb.md
+++ b/docs/database/dynamodb.md
@@ -29,9 +29,9 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` |  |
| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` |  |
-**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[1] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`rpc.system` 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.
@@ -67,9 +67,9 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` |  |
| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` |  |
-**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[1] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`rpc.system` 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.
@@ -109,9 +109,9 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` |  |
| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` |  |
-**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[1] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`rpc.system` 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.
@@ -147,9 +147,9 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` |  |
| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` |  |
-**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[1] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`rpc.system` 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.
@@ -183,9 +183,9 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` |  |
| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` |  |
-**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[1] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`rpc.system` 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.
@@ -219,9 +219,9 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` |  |
| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` |  |
-**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[1] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`rpc.system` 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.
@@ -258,9 +258,9 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` |  |
| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` |  |
-**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[1] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`rpc.system` 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.
@@ -296,9 +296,9 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` |  |
| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` |  |
-**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[1] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`rpc.system` 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.
@@ -334,9 +334,9 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` |  |
| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` |  |
-**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[1] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`rpc.system` 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.
@@ -378,9 +378,9 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` |  |
| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` |  |
-**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[1] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`rpc.system` 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.
@@ -425,9 +425,9 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` |  |
| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` |  |
-**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[1] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`rpc.system` 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.
@@ -463,9 +463,9 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` |  |
| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` |  |
-**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[1] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`rpc.system` 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.
@@ -504,9 +504,9 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` |  |
| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` |  |
-**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[1] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`rpc.system` 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/docs/database/elasticsearch.md b/docs/database/elasticsearch.md
index ea8f7c0bb7..8e8838a3cf 100644
--- a/docs/database/elasticsearch.md
+++ b/docs/database/elasticsearch.md
@@ -39,9 +39,9 @@ The **span name** follows the [general database span name guidelines](database-s
| [`db.query.text`](/docs/attributes-registry/db.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. [13] | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | `Recommended` [14] |  |
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-**[1]:** The `db.operation.name` SHOULD match the endpoint identifier provided in the request (see the [Elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json)).
+**[1] `db.operation.name`:** The `db.operation.name` SHOULD match the endpoint identifier provided in the request (see the [Elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json)).
-**[2]:** HTTP request method value SHOULD be "known" to the instrumentation.
+**[2] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@@ -56,7 +56,7 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
-**[3]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment
+**[3] `url.full`:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment
is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless.
`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`.
@@ -80,37 +80,37 @@ This list is subject to change over time.
When a query string value is redacted, the query string key SHOULD still be preserved, e.g.
`https://www.example.com/path?color=blue&sig=REDACTED`.
-**[4]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names.
+**[4] `db.elasticsearch.path_parts`:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names.
-**[5]:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
+**[5] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
-**[6]:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[6] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[8]:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[9]:** The query may target multiple indices or data streams, in which case it SHOULD be a comma separated list of those. If the query doesn't target a specific index, this field MUST NOT be set.
+**[9] `db.collection.name`:** The query may target multiple indices or data streams, in which case it SHOULD be a comma separated list of those. If the query doesn't target a specific index, this field MUST NOT be set.
-**[10]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header.
+**[10] `db.elasticsearch.node.name`:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header.
-**[11]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header.
+**[11] `db.namespace`:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header.
-**[12]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[12] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[13]:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
**[14]:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information.
-**[15]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
The following attributes can be important for making sampling decisions
and SHOULD be provided **at span creation time** (if provided at all):
diff --git a/docs/database/hbase.md b/docs/database/hbase.md
index 62bc5a78a5..7150655a03 100644
--- a/docs/database/hbase.md
+++ b/docs/database/hbase.md
@@ -30,14 +30,14 @@ The Semantic Conventions for [HBase](https://hbase.apache.org/) extend and overr
| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [8] | `2`; `3`; `4` | `Recommended` |  |
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-**[1]:** If table name includes the namespace, the `db.collection.name` SHOULD be set to the full table name.
+**[1] `db.collection.name`:** If table name includes the namespace, the `db.collection.name` SHOULD be set to the full table name.
-**[2]:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
+**[2] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system.
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
This attribute has stability level RELEASE CANDIDATE.
-**[3]:** It is RECOMMENDED to capture the value as provided by the application
+**[3] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization.
A single database query may involve multiple operations. If the operation
@@ -52,22 +52,22 @@ system specific term if more applicable.
This attribute has stability level RELEASE CANDIDATE.
-**[4]:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
+**[4] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
-**[5]:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[5] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[7]:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[8]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[8] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[9]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[9] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
The following attributes can be important for making sampling decisions
and SHOULD be provided **at span creation time** (if provided at all):
diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md
index 05b25a8e2d..d313f41cfb 100644
--- a/docs/database/mariadb.md
+++ b/docs/database/mariadb.md
@@ -34,7 +34,7 @@ The Semantic Conventions for *MariaDB* extend and override the [Database Semanti
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` |  |
-**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
+**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
A single database query may involve multiple collections.
@@ -52,7 +52,7 @@ This attribute has stability level RELEASE CANDIDATE.
**[2]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
-**[3]:** A connection's currently associated database may change during its lifetime, e.g. from executing `USE `.
+**[3] `db.namespace`:** A connection's currently associated database may change during its lifetime, e.g. from executing `USE `.
If instrumentation is unable to capture the connection's currently associated database on each query
without triggering an additional query to be executed (e.g. `SELECT DATABASE()`),
@@ -62,12 +62,12 @@ Instrumentation SHOULD document if `db.namespace` reflects the database provided
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-**[4]:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
+**[4] `db.operation.name`:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed.
**[5]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-**[6]:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
+**[6] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
return code which is adopted by some database systems like PostgreSQL.
See [PostgreSQL error codes](https://www.postgresql.org/docs/current/errcodes-appendix.html)
for the details.
@@ -103,24 +103,24 @@ For example, generic DB instrumentation that detected an error and has
SQLSTATE `"42000"` and vendor-specific `1071` should set
`db.response.status_code` to `"42000/1071"`."
-**[7]:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[7] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[8]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[9]:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[11]:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+**[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[12]:** if readily available or if instrumentation supports query summarization.
-**[13]:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
@@ -128,9 +128,9 @@ This attribute has stability level RELEASE CANDIDATE.
**[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
-**[15]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
+**[16] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`.
This attribute has stability level RELEASE CANDIDATE.
diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md
index 2d4c9a6f85..2d8d48fea5 100644
--- a/docs/database/mongodb.md
+++ b/docs/database/mongodb.md
@@ -30,7 +30,7 @@ The Semantic Conventions for [MongoDB](https://www.mongodb.com/) extend and over
| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [8] | `2`; `3`; `4` | `Recommended` |  |
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
+**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
A single database query may involve multiple collections.
@@ -46,26 +46,26 @@ SHOULD NOT be captured.
This attribute has stability level RELEASE CANDIDATE.
-**[2]:** See [MongoDB database commands](https://www.mongodb.com/docs/manual/reference/command/).
+**[2] `db.operation.name`:** See [MongoDB database commands](https://www.mongodb.com/docs/manual/reference/command/).
-**[3]:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
+**[3] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
**[4]:** If the operation failed and error code is available.
-**[5]:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[5] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[7]:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[8]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[8] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[9]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[9] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
The following attributes can be important for making sampling decisions
and SHOULD be provided **at span creation time** (if provided at all):
diff --git a/docs/database/mssql.md b/docs/database/mssql.md
index 7ef511e56c..475c8ff80e 100644
--- a/docs/database/mssql.md
+++ b/docs/database/mssql.md
@@ -34,7 +34,7 @@ The Semantic Conventions for the *Microsoft SQL Server* extend and override the
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` |  |
-**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
+**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
A single database query may involve multiple collections.
@@ -52,7 +52,7 @@ This attribute has stability level RELEASE CANDIDATE.
**[2]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
-**[3]:** When connected to a default instance, `db.namespace` SHOULD be set to the name of
+**[3] `db.namespace`:** When connected to a default instance, `db.namespace` SHOULD be set to the name of
the database. When connected to a [named instance](https://learn.microsoft.com/sql/connect/jdbc/building-the-connection-url#named-and-multiple-sql-server-instances),
`db.namespace` SHOULD be set to the combination of instance and database name following the `{instance_name}.{database_name}` pattern.
@@ -66,31 +66,31 @@ Instrumentation SHOULD document if `db.namespace` reflects the database provided
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-**[4]:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
+**[4] `db.operation.name`:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed.
**[5]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-**[6]:** Microsoft SQL Server does not report SQLSTATE.
+**[6] `db.response.status_code`:** Microsoft SQL Server does not report SQLSTATE.
-**[7]:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[7] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[8]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[9]:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[11]:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+**[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[12]:** if readily available or if instrumentation supports query summarization.
-**[13]:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
@@ -98,9 +98,9 @@ This attribute has stability level RELEASE CANDIDATE.
**[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
-**[15]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
+**[16] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`.
This attribute has stability level RELEASE CANDIDATE.
diff --git a/docs/database/mysql.md b/docs/database/mysql.md
index f9df3f6355..7ad61d747b 100644
--- a/docs/database/mysql.md
+++ b/docs/database/mysql.md
@@ -34,7 +34,7 @@ The Semantic Conventions for *MySQL* extend and override the [Database Semantic
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` |  |
-**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
+**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
A single database query may involve multiple collections.
@@ -52,7 +52,7 @@ This attribute has stability level RELEASE CANDIDATE.
**[2]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
-**[3]:** A connection's currently associated database may change during its lifetime, e.g. from executing `USE `.
+**[3] `db.namespace`:** A connection's currently associated database may change during its lifetime, e.g. from executing `USE `.
If instrumentation is unable to capture the connection's currently associated database on each query
without triggering an additional query to be executed (e.g. `SELECT DATABASE()`),
@@ -62,12 +62,12 @@ Instrumentation SHOULD document if `db.namespace` reflects the database provided
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-**[4]:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
+**[4] `db.operation.name`:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed.
**[5]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-**[6]:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
+**[6] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
return code which is adopted by some database systems like PostgreSQL.
See [PostgreSQL error codes](https://www.postgresql.org/docs/current/errcodes-appendix.html)
for the details.
@@ -103,24 +103,24 @@ For example, generic DB instrumentation that detected an error and has
SQLSTATE `"42000"` and vendor-specific `1071` should set
`db.response.status_code` to `"42000/1071"`."
-**[7]:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[7] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[8]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[9]:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[11]:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+**[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[12]:** if readily available or if instrumentation supports query summarization.
-**[13]:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
@@ -128,9 +128,9 @@ This attribute has stability level RELEASE CANDIDATE.
**[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
-**[15]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
+**[16] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`.
This attribute has stability level RELEASE CANDIDATE.
diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md
index 93021ce139..9f1586f42c 100644
--- a/docs/database/postgresql.md
+++ b/docs/database/postgresql.md
@@ -34,7 +34,7 @@ The Semantic Conventions for *PostgreSQL* extend and override the [Database Sema
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` |  |
-**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
+**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
A single database query may involve multiple collections.
@@ -52,7 +52,7 @@ This attribute has stability level RELEASE CANDIDATE.
**[2]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
-**[3]:** `db.namespace` SHOULD be set to the combination of database and schema name following the `{database}.{schema}` pattern.
+**[3] `db.namespace`:** `db.namespace` SHOULD be set to the combination of database and schema name following the `{database}.{schema}` pattern.
A connection's currently associated database may change during its lifetime, e.g. from executing `SET search_path TO `.
If the search path has multiple schemas, the first schema in the search path SHOULD be used.
@@ -69,12 +69,12 @@ Instrumentation SHOULD document if `db.namespace` reflects the user provided whe
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-**[4]:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
+**[4] `db.operation.name`:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed.
**[5]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-**[6]:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
+**[6] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
return code which is adopted by some database systems like PostgreSQL.
See [PostgreSQL error codes](https://www.postgresql.org/docs/current/errcodes-appendix.html)
for the details.
@@ -110,24 +110,24 @@ For example, generic DB instrumentation that detected an error and has
SQLSTATE `"42000"` and vendor-specific `1071` should set
`db.response.status_code` to `"42000/1071"`."
-**[7]:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[7] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[8]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[9]:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[11]:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+**[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[12]:** if readily available or if instrumentation supports query summarization.
-**[13]:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
@@ -135,9 +135,9 @@ This attribute has stability level RELEASE CANDIDATE.
**[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
-**[15]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
+**[16] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`.
This attribute has stability level RELEASE CANDIDATE.
diff --git a/docs/database/redis.md b/docs/database/redis.md
index 6408cd35d8..46ff5ec2a5 100644
--- a/docs/database/redis.md
+++ b/docs/database/redis.md
@@ -39,7 +39,7 @@ looking confusing.
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [13] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [14] | `someval`; `55` | `Opt-In` |  |
-**[1]:** A connection's currently associated database index may change during its lifetime, e.g. from executing `SELECT `.
+**[1] `db.namespace`:** A connection's currently associated database index may change during its lifetime, e.g. from executing `SELECT `.
If instrumentation is unable to capture the connection's currently associated database index on each query
without triggering an additional query to be executed,
@@ -47,7 +47,7 @@ then it is RECOMMENDED to fallback and use the database index provided when the
Instrumentation SHOULD document if `db.namespace` reflects the database index provided when the connection was established.
-**[2]:** It is RECOMMENDED to capture the value as provided by the application
+**[2] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization.
A single database query may involve multiple operations. If the operation
@@ -64,34 +64,34 @@ This attribute has stability level RELEASE CANDIDATE.
**[3]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-**[4]:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
+**[4] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
**[5]:** If the operation failed and status code is available.
-**[6]:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[6] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[8]:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[9]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[9] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[10]:** For **Redis**, the value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`.
+**[10] `db.query.text`:** For **Redis**, the value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`.
**[11]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text.
See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
-**[12]:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
+**[12] `network.peer.address`:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
-**[13]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[13] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[14]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
+**[14] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`.
This attribute has stability level RELEASE CANDIDATE.
diff --git a/docs/database/sql.md b/docs/database/sql.md
index 6154f8aa32..65ee866da4 100644
--- a/docs/database/sql.md
+++ b/docs/database/sql.md
@@ -58,7 +58,7 @@ Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic co
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` |  |
-**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
+**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
A single database query may involve multiple collections.
@@ -76,7 +76,7 @@ This attribute has stability level RELEASE CANDIDATE.
**[2]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
-**[3]:** If a database system has multiple namespace components (e.g. schema name and database name), they SHOULD be concatenated
+**[3] `db.namespace`:** If a database system has multiple namespace components (e.g. schema name and database name), they SHOULD be concatenated
(potentially using database system specific conventions) from most general to most
specific namespace component, and more specific namespaces SHOULD NOT be captured without
the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
@@ -94,12 +94,12 @@ Instrumentation SHOULD document if `db.namespace` reflects the database provided
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-**[4]:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
+**[4] `db.operation.name`:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed.
**[5]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-**[6]:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
+**[6] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
return code which is adopted by some database systems like PostgreSQL.
See [PostgreSQL error codes](https://www.postgresql.org/docs/current/errcodes-appendix.html)
for the details.
@@ -135,24 +135,24 @@ For example, generic DB instrumentation that detected an error and has
SQLSTATE `"42000"` and vendor-specific `1071` should set
`db.response.status_code` to `"42000/1071"`."
-**[7]:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[7] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[8]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[9]:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[11]:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+**[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[12]:** if readily available or if instrumentation supports query summarization.
-**[13]:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
@@ -160,9 +160,9 @@ This attribute has stability level RELEASE CANDIDATE.
**[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
-**[15]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
+**[16] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`.
This attribute has stability level RELEASE CANDIDATE.
diff --git a/docs/dns/dns-metrics.md b/docs/dns/dns-metrics.md
index ca0c7555e7..2abf5a5278 100644
--- a/docs/dns/dns-metrics.md
+++ b/docs/dns/dns-metrics.md
@@ -43,9 +43,9 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
| [`dns.question.name`](/docs/attributes-registry/dns.md) | string | The name being queried. [1] | `www.example.com`; `dot.net` | `Required` |  |
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes the error the DNS lookup failed with. [2] | `host_not_found`; `no_recovery`; `java.net.UnknownHostException` | `Conditionally Required` if and only if an error has occurred. |  |
-**[1]:** If the name field contains non-printable characters (below 32 or above 126), those characters should be represented as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. Tabs, carriage returns, and line feeds should be converted to \t, \r, and \n respectively.
+**[1] `dns.question.name`:** If the name field contains non-printable characters (below 32 or above 126), those characters should be represented as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. Tabs, carriage returns, and line feeds should be converted to \t, \r, and \n respectively.
-**[2]:** Instrumentations SHOULD use error code such as one of errors reported by `getaddrinfo`([Linux or other POSIX systems](https://man7.org/linux/man-pages/man3/getaddrinfo.3.html) / [Windows](https://learn.microsoft.com/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo)) or one reported by the runtime or client library. If error code is not available, the full name of exception type SHOULD be used.
+**[2] `error.type`:** Instrumentations SHOULD use error code such as one of errors reported by `getaddrinfo`([Linux or other POSIX systems](https://man7.org/linux/man-pages/man3/getaddrinfo.3.html) / [Windows](https://learn.microsoft.com/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo)) or one reported by the runtime or client library. If error code is not available, the full name of exception type SHOULD be used.
`error.type` 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/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md
index 8b7cfdcb1a..aa2daa4aaa 100644
--- a/docs/dotnet/dotnet-aspnetcore-metrics.md
+++ b/docs/dotnet/dotnet-aspnetcore-metrics.md
@@ -51,7 +51,7 @@ All routing metrics are reported by the `Microsoft.AspNetCore.Routing` meter.
| [`aspnetcore.routing.is_fallback`](/docs/attributes-registry/aspnetcore.md) | boolean | A value that indicates whether the matched route is a fallback route. | `true` | `Conditionally Required` if and only if a route was successfully matched. |  |
| [`http.route`](/docs/attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` if and only if a route was successfully matched. |  |
-**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
+**[1] `http.route`:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
`aspnetcore.routing.match_status` 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.
@@ -91,7 +91,7 @@ Exceptions Metric is reported by the `Microsoft.AspNetCore.Diagnostics` meter.
| [`error.type`](/docs/attributes-registry/error.md) | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | `Required` |  |
| [`aspnetcore.diagnostics.handler.type`](/docs/attributes-registry/aspnetcore.md) | string | Full type name of the [`IExceptionHandler`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.diagnostics.iexceptionhandler) implementation that handled the exception. | `Contoso.MyHandler` | `Conditionally Required` [2] |  |
-**[1]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
+**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
When `error.type` is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md
index f63ace4021..236613ed37 100644
--- a/docs/dotnet/dotnet-kestrel-metrics.md
+++ b/docs/dotnet/dotnet-kestrel-metrics.md
@@ -52,17 +52,17 @@ In case instrumentation does not recognize `EndPoint` implementation, it sets th
| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Recommended` |  |
-**[1]:** The value SHOULD be normalized to lowercase.
+**[1] `network.transport`:** The value SHOULD be normalized to lowercase.
Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport. For example
different processes could be listening on TCP port 12345 and UDP port 12345.
-**[2]:** The value SHOULD be normalized to lowercase.
+**[2] `network.type`:** The value SHOULD be normalized to lowercase.
-**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[3] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
`network.transport` 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.
@@ -116,7 +116,7 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Recommended` |  |
| [`tls.protocol.version`](/docs/attributes-registry/tls.md) | string | Numeric part of the version parsed from the original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) | `1.2`; `3` | `Recommended` |  |
-**[1]:** Starting from .NET 9, Kestrel `kestrel.connection.duration` metric reports
+**[1] `error.type`:** Starting from .NET 9, Kestrel `kestrel.connection.duration` metric reports
the following errors types when a corresponding error occurs:
| Value | Description | Stability |
@@ -168,21 +168,21 @@ the following errors types when a corresponding error occurs:
In other cases, `error.type` contains the fully qualified type name of the exception.
-**[2]:** The value SHOULD be normalized to lowercase.
+**[2] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
-**[3]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
+**[3] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
-**[4]:** The value SHOULD be normalized to lowercase.
+**[4] `network.transport`:** The value SHOULD be normalized to lowercase.
Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport. For example
different processes could be listening on TCP port 12345 and UDP port 12345.
-**[5]:** The value SHOULD be normalized to lowercase.
+**[5] `network.type`:** The value SHOULD be normalized to lowercase.
-**[6]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[6] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
`error.type` 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.
@@ -235,17 +235,17 @@ Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0
| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Recommended` |  |
-**[1]:** The value SHOULD be normalized to lowercase.
+**[1] `network.transport`:** The value SHOULD be normalized to lowercase.
Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport. For example
different processes could be listening on TCP port 12345 and UDP port 12345.
-**[2]:** The value SHOULD be normalized to lowercase.
+**[2] `network.type`:** The value SHOULD be normalized to lowercase.
-**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[3] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
`network.transport` 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.
@@ -291,17 +291,17 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Recommended` |  |
-**[1]:** The value SHOULD be normalized to lowercase.
+**[1] `network.transport`:** The value SHOULD be normalized to lowercase.
Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport. For example
different processes could be listening on TCP port 12345 and UDP port 12345.
-**[2]:** The value SHOULD be normalized to lowercase.
+**[2] `network.type`:** The value SHOULD be normalized to lowercase.
-**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[3] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
`network.transport` 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.
@@ -349,21 +349,21 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Recommended` |  |
-**[1]:** The value SHOULD be normalized to lowercase.
+**[1] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
-**[2]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
+**[2] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
-**[3]:** The value SHOULD be normalized to lowercase.
+**[3] `network.transport`:** The value SHOULD be normalized to lowercase.
Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport. For example
different processes could be listening on TCP port 12345 and UDP port 12345.
-**[4]:** The value SHOULD be normalized to lowercase.
+**[4] `network.type`:** The value SHOULD be normalized to lowercase.
-**[5]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[5] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
`network.transport` 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.
@@ -411,17 +411,17 @@ Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0
| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Recommended` |  |
-**[1]:** The value SHOULD be normalized to lowercase.
+**[1] `network.transport`:** The value SHOULD be normalized to lowercase.
Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport. For example
different processes could be listening on TCP port 12345 and UDP port 12345.
-**[2]:** The value SHOULD be normalized to lowercase.
+**[2] `network.type`:** The value SHOULD be normalized to lowercase.
-**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[3] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
`network.transport` 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.
@@ -473,19 +473,19 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [5] | `80`; `8080`; `443` | `Recommended` |  |
| [`tls.protocol.version`](/docs/attributes-registry/tls.md) | string | Numeric part of the version parsed from the original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) | `1.2`; `3` | `Recommended` |  |
-**[1]:** Captures the exception type when a TLS handshake fails.
+**[1] `error.type`:** Captures the exception type when a TLS handshake fails.
-**[2]:** The value SHOULD be normalized to lowercase.
+**[2] `network.transport`:** The value SHOULD be normalized to lowercase.
Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport. For example
different processes could be listening on TCP port 12345 and UDP port 12345.
-**[3]:** The value SHOULD be normalized to lowercase.
+**[3] `network.type`:** The value SHOULD be normalized to lowercase.
-**[4]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[4] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[5]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[5] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
`error.type` 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.
@@ -537,17 +537,17 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Recommended` |  |
-**[1]:** The value SHOULD be normalized to lowercase.
+**[1] `network.transport`:** The value SHOULD be normalized to lowercase.
Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport. For example
different processes could be listening on TCP port 12345 and UDP port 12345.
-**[2]:** The value SHOULD be normalized to lowercase.
+**[2] `network.type`:** The value SHOULD be normalized to lowercase.
-**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[3] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
`network.transport` 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/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md
index 03ab3062ac..ea634f37d6 100644
--- a/docs/exceptions/exceptions-spans.md
+++ b/docs/exceptions/exceptions-spans.md
@@ -64,7 +64,7 @@ This event describes a single exception.
**[2]:** Required if `exception.message` is not set, recommended otherwise.
-**[3]:** An exception is considered to have escaped (or left) the scope of a span,
+**[3] `exception.escaped`:** An exception is considered to have escaped (or left) the scope of a span,
if that span is ended while the exception is still logically "in flight".
This may be actually "in flight" in some languages (e.g. if the exception
is passed to a Context manager's `__exit__` method in Python) but will
diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md
index c58c761a70..d3200038e7 100644
--- a/docs/faas/aws-lambda.md
+++ b/docs/faas/aws-lambda.md
@@ -55,7 +55,7 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a
|---|---|---|---|---|---|
| [`aws.lambda.invoked_arn`](/docs/attributes-registry/aws.md) | 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 `cloud.resource_id` if an alias is involved.
+**[1] `aws.lambda.invoked_arn`:** This may be different from `cloud.resource_id` if an alias is involved.
diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md
index 764eadaa81..3428f037f6 100644
--- a/docs/faas/faas-spans.md
+++ b/docs/faas/faas-spans.md
@@ -51,7 +51,7 @@ If Spans following this convention are produced, a Resource of type `faas` MUST
| [`faas.invocation_id`](/docs/attributes-registry/faas.md) | string | The invocation ID of the current function invocation. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | `Recommended` |  |
| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. [2] | `datasource`; `http`; `pubsub` | `Recommended` |  |
-**[1]:** On some cloud providers, it may not be possible to determine the full ID at startup,
+**[1] `cloud.resource_id`:** 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.
@@ -69,7 +69,7 @@ The following well-known definitions MUST be used if you set this attribute and
This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share
a TracerProvider.
-**[2]:** For the server/consumer span on the incoming side,
+**[2] `faas.trigger`:** For the server/consumer span on the incoming side,
`faas.trigger` MUST be set.
Clients invoking FaaS instances usually cannot set `faas.trigger`,
@@ -141,7 +141,7 @@ For incoming FaaS spans, the span kind SHOULD be `SERVER`.
| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. [1] | `datasource`; `http`; `pubsub` | `Required` |  |
| [`faas.coldstart`](/docs/attributes-registry/faas.md) | boolean | A boolean that is true if the serverless function is executed for the first time (aka cold-start). | | `Recommended` |  |
-**[1]:** For the server/consumer span on the incoming side,
+**[1] `faas.trigger`:** For the server/consumer span on the incoming side,
`faas.trigger` MUST be set.
Clients invoking FaaS instances usually cannot set `faas.trigger`,
@@ -201,11 +201,11 @@ which the invoked FaaS instance reports about itself, if it's instrumented.
| [`faas.invoked_provider`](/docs/attributes-registry/faas.md) | string | The cloud provider of the invoked function. [2] | `alibaba_cloud`; `aws`; `azure` | `Required` |  |
| [`faas.invoked_region`](/docs/attributes-registry/faas.md) | string | The cloud region of the invoked function. [3] | `eu-central-1` | `Conditionally Required` [4] |  |
-**[1]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function.
+**[1] `faas.invoked_name`:** SHOULD be equal to the `faas.name` resource attribute of the invoked function.
-**[2]:** SHOULD be equal to the `cloud.provider` resource attribute of the invoked function.
+**[2] `faas.invoked_provider`:** SHOULD be equal to the `cloud.provider` resource attribute of the invoked function.
-**[3]:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function.
+**[3] `faas.invoked_region`:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function.
**[4]:** For some cloud providers, like AWS or GCP, the region in which a function is hosted is essential to uniquely identify the function and also part of its endpoint. Since it's part of the endpoint being called, the region is always known to clients. In these cases, `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional.
diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md
index 85964d8181..063d256c37 100644
--- a/docs/feature-flags/feature-flags-logs.md
+++ b/docs/feature-flags/feature-flags-logs.md
@@ -68,7 +68,7 @@ A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag valu
| [`feature_flag.system`](/docs/attributes-registry/feature-flag.md) | string | Identifies the feature flag provider. | `Flag Manager` | `Recommended` |  |
| [`feature_flag.version`](/docs/attributes-registry/feature-flag.md) | string | The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. | `1`; `01ABCDEF` | `Recommended` |  |
-**[1]:** If one of these values applies, then it MUST be used; otherwise, a custom value MAY be used.
+**[1] `error.type`:** If one of these values applies, then it MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
|---|---|---|
@@ -83,7 +83,7 @@ A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag valu
**[2]:** If and only if an error occurred during flag evaluation.
-**[3]:** A semantic identifier, commonly referred to as a variant, provides a means
+**[3] `feature_flag.variant`:** A semantic identifier, commonly referred to as a variant, provides a means
for referring to a value without including the value itself. This can
provide additional context for understanding the meaning behind a value.
For example, the variant `red` maybe be used for the value `#c05543`.
diff --git a/docs/gen-ai/azure-ai-inference.md b/docs/gen-ai/azure-ai-inference.md
index 7275e19c67..8820b2cd40 100644
--- a/docs/gen-ai/azure-ai-inference.md
+++ b/docs/gen-ai/azure-ai-inference.md
@@ -41,21 +41,21 @@ The Semantic Conventions for [Azure AI Inference](https://learn.microsoft.com/az
| [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of completion tokens as reported in the usage completion_tokens property of the response. | `180` | `Recommended` |  |
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
+**[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
-**[2]:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library,
+**[2] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library,
the canonical name of exception that occurred, or another low-cardinality error identifier.
Instrumentations SHOULD document the list of errors they report.
-**[3]:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
+**[3] `gen_ai.request.model`:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
-**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[5]:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.CognitiveServices` for all operations performed by Azure AI Inference clients.
+**[5] `az.namespace`:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.CognitiveServices` for all operations performed by Azure AI Inference clients.
-**[6]:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
+**[6] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
-**[7]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[7] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
`error.type` 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/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md
index 44eeadc31d..c5595966de 100644
--- a/docs/gen-ai/gen-ai-events.md
+++ b/docs/gen-ai/gen-ai-events.md
@@ -65,7 +65,7 @@ The following attributes apply to all GenAI events.
|---|---|---|---|---|---|
| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Recommended` |  |
-**[1]:** The `gen_ai.system` describes a family of GenAI models with specific model identified
+**[1] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified
by `gen_ai.request.model` and `gen_ai.response.model` attributes.
The actual GenAI product may differ from the one identified by the client.
diff --git a/docs/gen-ai/gen-ai-metrics.md b/docs/gen-ai/gen-ai-metrics.md
index c8cba89124..0ab10904e1 100644
--- a/docs/gen-ai/gen-ai-metrics.md
+++ b/docs/gen-ai/gen-ai-metrics.md
@@ -69,9 +69,9 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of [1, 4, 16, 64
| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` |  |
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
+**[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
-**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified
+**[2] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified
by `gen_ai.request.model` and `gen_ai.response.model` attributes.
The actual GenAI product may differ from the one identified by the client.
@@ -81,9 +81,9 @@ is set to `openai` based on the instrumentation's best knowledge.
For custom model, a custom friendly name SHOULD be used.
If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
-**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[3] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[4]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[4] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
`gen_ai.operation.name` 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.
@@ -141,9 +141,9 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of [0.01, 0.02,
| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` |  |
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
+**[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
-**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified
+**[2] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified
by `gen_ai.request.model` and `gen_ai.response.model` attributes.
The actual GenAI product may differ from the one identified by the client.
@@ -153,13 +153,13 @@ is set to `openai` based on the instrumentation's best knowledge.
For custom model, a custom friendly name SHOULD be used.
If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
-**[3]:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library,
+**[3] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library,
the canonical name of exception that occurred, or another low-cardinality error identifier.
Instrumentations SHOULD document the list of errors they report.
-**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[5]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[5] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
`error.type` 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.
@@ -223,9 +223,9 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of
| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` |  |
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
+**[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
-**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified
+**[2] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified
by `gen_ai.request.model` and `gen_ai.response.model` attributes.
The actual GenAI product may differ from the one identified by the client.
@@ -235,13 +235,13 @@ is set to `openai` based on the instrumentation's best knowledge.
For custom model, a custom friendly name SHOULD be used.
If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
-**[3]:** The `error.type` SHOULD match the error code returned by the Generative AI service,
+**[3] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI service,
the canonical name of exception that occurred, or another low-cardinality error identifier.
Instrumentations SHOULD document the list of errors they report.
-**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[5]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[5] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
`error.type` 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.
@@ -304,9 +304,9 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of
| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` |  |
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
+**[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
-**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified
+**[2] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified
by `gen_ai.request.model` and `gen_ai.response.model` attributes.
The actual GenAI product may differ from the one identified by the client.
@@ -316,9 +316,9 @@ is set to `openai` based on the instrumentation's best knowledge.
For custom model, a custom friendly name SHOULD be used.
If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
-**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[3] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[4]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[4] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
`gen_ai.operation.name` 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.
@@ -374,9 +374,9 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of
| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` |  |
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
+**[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
-**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified
+**[2] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified
by `gen_ai.request.model` and `gen_ai.response.model` attributes.
The actual GenAI product may differ from the one identified by the client.
@@ -386,9 +386,9 @@ is set to `openai` based on the instrumentation's best knowledge.
For custom model, a custom friendly name SHOULD be used.
If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
-**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[3] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[4]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[4] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
`gen_ai.operation.name` 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/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md
index 4bea84e4d5..e4bc72c0e5 100644
--- a/docs/gen-ai/gen-ai-spans.md
+++ b/docs/gen-ai/gen-ai-spans.md
@@ -62,9 +62,9 @@ These attributes track input data and metadata for a request to an GenAI model.
| [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI response (completion). | `180` | `Recommended` |  |
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
+**[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
-**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified
+**[2] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified
by `gen_ai.request.model` and `gen_ai.response.model` attributes.
The actual GenAI product may differ from the one identified by the client.
@@ -74,17 +74,17 @@ is set to `openai` based on the instrumentation's best knowledge.
For custom model, a custom friendly name SHOULD be used.
If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
-**[3]:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library,
+**[3] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library,
the canonical name of exception that occurred, or another low-cardinality error identifier.
Instrumentations SHOULD document the list of errors they report.
-**[4]:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
+**[4] `gen_ai.request.model`:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
-**[5]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[5] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[6]:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
+**[6] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
-**[7]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[7] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
`error.type` 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/docs/gen-ai/openai.md b/docs/gen-ai/openai.md
index 7d77082b70..ce9114ecde 100644
--- a/docs/gen-ai/openai.md
+++ b/docs/gen-ai/openai.md
@@ -58,11 +58,11 @@ attributes and ones specific the OpenAI.
| [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the completions from OpenAI. | `180` | `Recommended` |  |
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
+**[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
-**[2]:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
+**[2] `gen_ai.request.model`:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
-**[3]:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library,
+**[3] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library,
the canonical name of exception that occurred, or another low-cardinality error identifier.
Instrumentations SHOULD document the list of errors they report.
@@ -70,11 +70,11 @@ Instrumentations SHOULD document the list of errors they report.
**[5]:** if the response was received and includes a service_tier
-**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[7]:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
+**[7] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
-**[8]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[8] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
`error.type` 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/docs/general/attributes.md b/docs/general/attributes.md
index 118dffed70..d0d5024933 100644
--- a/docs/general/attributes.md
+++ b/docs/general/attributes.md
@@ -78,9 +78,9 @@ if they do not cause breaking changes to HTTP semantic conventions.
| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | `Recommended` |  |
-**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[1] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[2] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
@@ -125,9 +125,9 @@ if they do not cause breaking changes to HTTP semantic conventions.
| [`client.address`](/docs/attributes-registry/client.md) | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`client.port`](/docs/attributes-registry/client.md) | int | Client port number. [2] | `65123` | `Recommended` |  |
-**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available.
+**[1] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available.
-**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available.
+**[2] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available.
@@ -157,7 +157,7 @@ This also covers unidirectional UDP flows and peer-to-peer communication where t
| [`source.address`](/docs/attributes-registry/source.md) | string | Source address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `source.example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`source.port`](/docs/attributes-registry/source.md) | int | Source port number | `3389`; `2888` | `Recommended` |  |
-**[1]:** When observed from the destination side, and when communicating through an intermediary, `source.address` SHOULD represent the source address behind any intermediaries, for example proxies, if it's available.
+**[1] `source.address`:** When observed from the destination side, and when communicating through an intermediary, `source.address` SHOULD represent the source address behind any intermediaries, for example proxies, if it's available.
@@ -180,7 +180,7 @@ Destination fields capture details about the receiver of a network exchange/pack
| [`destination.address`](/docs/attributes-registry/destination.md) | string | Destination address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `destination.example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`destination.port`](/docs/attributes-registry/destination.md) | int | Destination port number | `3389`; `2888` | `Recommended` |  |
-**[1]:** When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent the destination address behind any intermediaries, for example proxies, if it's available.
+**[1] `destination.address`:** When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent the destination address behind any intermediaries, for example proxies, if it's available.
@@ -214,17 +214,17 @@ if they do not cause breaking changes to HTTP semantic conventions.
| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` | `Recommended` |  |
| [`network.type`](/docs/attributes-registry/network.md) | string | [OSI network layer](https://wikipedia.org/wiki/Network_layer) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | `Recommended` |  |
-**[1]:** The value SHOULD be normalized to lowercase.
+**[1] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
-**[2]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
+**[2] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
-**[3]:** The value SHOULD be normalized to lowercase.
+**[3] `network.transport`:** The value SHOULD be normalized to lowercase.
Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport. For example
different processes could be listening on TCP port 12345 and UDP port 12345.
-**[4]:** The value SHOULD be normalized to lowercase.
+**[4] `network.type`:** The value SHOULD be normalized to lowercase.
`network.transport` 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/docs/general/events.md b/docs/general/events.md
index 73bf87be5c..da314d9bf6 100644
--- a/docs/general/events.md
+++ b/docs/general/events.md
@@ -45,7 +45,7 @@ structure and semantics will also be defined.
|---|---|---|---|---|---|
| [`event.name`](/docs/attributes-registry/event.md) | string | Identifies the class / type of event. [1] | `browser.mouse.click`; `device.app.lifecycle` | `Required` |  |
-**[1]:** Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md). Notably, event names are namespaced to avoid collisions and provide a clean separation of semantics for events in separate domains like browser, mobile, and kubernetes.
+**[1] `event.name`:** Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md). Notably, event names are namespaced to avoid collisions and provide a clean separation of semantics for events in separate domains like browser, mobile, and kubernetes.
diff --git a/docs/general/logs.md b/docs/general/logs.md
index 4f3f8e9af8..3e350512a5 100644
--- a/docs/general/logs.md
+++ b/docs/general/logs.md
@@ -47,9 +47,9 @@ These attributes may be used for identifying a Log Record.
| [`log.record.original`](/docs/attributes-registry/log.md) | string | The complete original Log Record. [1] | `77 <86>1 2015-08-06T21:58:59.694Z 192.168.2.133 inactive - - - Something happened`; `[INFO] 8/3/24 12:34:56 Something happened` | `Opt-In` |  |
| [`log.record.uid`](/docs/attributes-registry/log.md) | string | A unique identifier for the Log Record. [2] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | `Opt-In` |  |
-**[1]:** This value MAY be added when processing a Log Record which was originally transmitted as a string or equivalent data type AND the Body field of the Log Record does not contain the same value. (e.g. a syslog or a log record read from a file.)
+**[1] `log.record.original`:** This value MAY be added when processing a Log Record which was originally transmitted as a string or equivalent data type AND the Body field of the Log Record does not contain the same value. (e.g. a syslog or a log record read from a file.)
-**[2]:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values.
+**[2] `log.record.uid`:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values.
The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), but other identifiers (e.g. UUID) may be used as needed.
diff --git a/docs/general/trace-compatibility.md b/docs/general/trace-compatibility.md
index c3a22cf2e3..ce48cfb79c 100644
--- a/docs/general/trace-compatibility.md
+++ b/docs/general/trace-compatibility.md
@@ -35,7 +35,7 @@ between a child Span and a parent Span, as defined by
|---|---|---|---|---|---|
| [`opentracing.ref_type`](/docs/attributes-registry/opentracing.md) | string | Parent-child Reference type [1] | `child_of`; `follows_from` | `Recommended` |  |
-**[1]:** The causal relationship between a child Span and a parent Span.
+**[1] `opentracing.ref_type`:** The causal relationship between a child Span and a parent Span.
`opentracing.ref_type` 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/docs/graphql/graphql-spans.md b/docs/graphql/graphql-spans.md
index 6eee813b07..1bc341996b 100644
--- a/docs/graphql/graphql-spans.md
+++ b/docs/graphql/graphql-spans.md
@@ -35,7 +35,7 @@ the span SHOULD be named `GraphQL Operation`.
| [`graphql.operation.name`](/docs/attributes-registry/graphql.md) | string | The name of the operation being executed. | `findBookById` | `Recommended` |  |
| [`graphql.operation.type`](/docs/attributes-registry/graphql.md) | string | The type of the operation being executed. | `query`; `mutation`; `subscription` | `Recommended` |  |
-**[1]:** The value may be sanitized to exclude sensitive information.
+**[1] `graphql.document`:** The value may be sanitized to exclude sensitive information.
`graphql.operation.type` 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/docs/hardware/common.md b/docs/hardware/common.md
index e8b924af71..d71c418558 100644
--- a/docs/hardware/common.md
+++ b/docs/hardware/common.md
@@ -40,7 +40,7 @@ monitored component:
| [`hw.name`](/docs/attributes-registry/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` |  |
| [`hw.parent`](/docs/attributes-registry/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` |  |
-**[1]:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`.
+**[1] `hw.type`:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`.
`hw.type` 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.
@@ -88,7 +88,7 @@ This metric is [recommended][MetricRecommended].
| [`hw.name`](/docs/attributes-registry/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` |  |
| [`hw.parent`](/docs/attributes-registry/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` |  |
-**[1]:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`.
+**[1] `hw.type`:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`.
`hw.type` 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.
@@ -137,9 +137,9 @@ This metric is [recommended][MetricRecommended].
| [`hw.name`](/docs/attributes-registry/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` |  |
| [`hw.parent`](/docs/attributes-registry/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` |  |
-**[1]:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`.
+**[1] `hw.type`:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`.
-**[2]:** The `error.type` SHOULD match the error code reported by the component, the canonical name of the error, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report.
+**[2] `error.type`:** The `error.type` SHOULD match the error code reported by the component, the canonical name of the error, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report.
`error.type` 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.
@@ -195,7 +195,7 @@ This metric is [recommended][MetricRecommended].
| [`hw.name`](/docs/attributes-registry/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` |  |
| [`hw.parent`](/docs/attributes-registry/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` |  |
-**[1]:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`.
+**[1] `hw.type`:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`.
`hw.type` 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.
@@ -246,7 +246,7 @@ This metric is [recommended][MetricRecommended].
| [`hw.name`](/docs/attributes-registry/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` |  |
| [`hw.parent`](/docs/attributes-registry/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` |  |
-**[1]:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`.
+**[1] `hw.type`:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`.
`hw.state` 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/docs/http/http-metrics.md b/docs/http/http-metrics.md
index 94f4683f73..eb29e75803 100644
--- a/docs/http/http-metrics.md
+++ b/docs/http/http-metrics.md
@@ -90,7 +90,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` |  |
-**[1]:** HTTP request method value SHOULD be "known" to the instrumentation.
+**[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@@ -105,9 +105,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
-**[2]:** The scheme of the original client request, if known (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request.
+**[2] `url.scheme`:** The scheme of the original client request, if known (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request.
-**[3]:** If the request fails with an error before response status code was sent or received,
+**[3] `error.type`:** If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable)
or a component-specific low cardinality error identifier.
@@ -124,21 +124,21 @@ additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
-**[4]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
+**[4] `http.route`:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
-**[5]:** The value SHOULD be normalized to lowercase.
+**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
**[6]:** If not `http` and `network.protocol.version` is set.
-**[7]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
+**[7] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
-**[8]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
+**[8] `server.address`:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
> **Warning**
> Since this attribute is based on HTTP headers, opting in to it may allow an attacker
> to trigger cardinality limits, degrading the usefulness of the metric.
-**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
+**[9] `server.port`:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
> **Warning**
> Since this attribute is based on HTTP headers, opting in to it may allow an attacker
> to trigger cardinality limits, degrading the usefulness of the metric.
@@ -191,7 +191,7 @@ This metric is optional.
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [3] | `80`; `8080`; `443` | `Opt-In` |  |
-**[1]:** HTTP request method value SHOULD be "known" to the instrumentation.
+**[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@@ -206,12 +206,12 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
-**[2]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
+**[2] `server.address`:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
> **Warning**
> Since this attribute is based on HTTP headers, opting in to it may allow an attacker
> to trigger cardinality limits, degrading the usefulness of the metric.
-**[3]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
+**[3] `server.port`:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
> **Warning**
> Since this attribute is based on HTTP headers, opting in to it may allow an attacker
> to trigger cardinality limits, degrading the usefulness of the metric.
@@ -265,7 +265,7 @@ This metric is optional.
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` |  |
-**[1]:** HTTP request method value SHOULD be "known" to the instrumentation.
+**[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@@ -280,9 +280,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
-**[2]:** The scheme of the original client request, if known (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request.
+**[2] `url.scheme`:** The scheme of the original client request, if known (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request.
-**[3]:** If the request fails with an error before response status code was sent or received,
+**[3] `error.type`:** If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable)
or a component-specific low cardinality error identifier.
@@ -299,21 +299,21 @@ additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
-**[4]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
+**[4] `http.route`:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
-**[5]:** The value SHOULD be normalized to lowercase.
+**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
**[6]:** If not `http` and `network.protocol.version` is set.
-**[7]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
+**[7] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
-**[8]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
+**[8] `server.address`:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
> **Warning**
> Since this attribute is based on HTTP headers, opting in to it may allow an attacker
> to trigger cardinality limits, degrading the usefulness of the metric.
-**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
+**[9] `server.port`:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
> **Warning**
> Since this attribute is based on HTTP headers, opting in to it may allow an attacker
> to trigger cardinality limits, degrading the usefulness of the metric.
@@ -373,7 +373,7 @@ This metric is optional.
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` |  |
-**[1]:** HTTP request method value SHOULD be "known" to the instrumentation.
+**[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@@ -388,9 +388,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
-**[2]:** The scheme of the original client request, if known (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request.
+**[2] `url.scheme`:** The scheme of the original client request, if known (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request.
-**[3]:** If the request fails with an error before response status code was sent or received,
+**[3] `error.type`:** If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable)
or a component-specific low cardinality error identifier.
@@ -407,21 +407,21 @@ additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
-**[4]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
+**[4] `http.route`:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
-**[5]:** The value SHOULD be normalized to lowercase.
+**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
**[6]:** If not `http` and `network.protocol.version` is set.
-**[7]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
+**[7] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
-**[8]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
+**[8] `server.address`:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
> **Warning**
> Since this attribute is based on HTTP headers, opting in to it may allow an attacker
> to trigger cardinality limits, degrading the usefulness of the metric.
-**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
+**[9] `server.port`:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
> **Warning**
> Since this attribute is based on HTTP headers, opting in to it may allow an attacker
> to trigger cardinality limits, degrading the usefulness of the metric.
@@ -487,7 +487,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | `Opt-In` |  |
| [`url.template`](/docs/attributes-registry/url.md) | string | The low-cardinality template of an [absolute path reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.2). [8] | `/users/{id}`; `/users/:id`; `/users?id={id}` | `Opt-In` |  |
-**[1]:** HTTP request method value SHOULD be "known" to the instrumentation.
+**[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@@ -502,11 +502,11 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
-**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used.
+**[2] `server.address`:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used.
-**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[3] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[4]:** If the request fails with an error before response status code was sent or received,
+**[4] `error.type`:** If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable)
or a component-specific low cardinality error identifier.
@@ -523,13 +523,13 @@ additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
-**[5]:** The value SHOULD be normalized to lowercase.
+**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
**[6]:** If not `http` and `network.protocol.version` is set.
-**[7]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
+**[7] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
-**[8]:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation.
+**[8] `url.template`:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation.
`error.type` 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.
@@ -586,7 +586,7 @@ This metric is optional.
| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [8] | `1.0`; `1.1`; `2`; `3` | `Recommended` |  |
| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | `Opt-In` |  |
-**[1]:** HTTP request method value SHOULD be "known" to the instrumentation.
+**[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@@ -601,11 +601,11 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
-**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used.
+**[2] `server.address`:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used.
-**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[3] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[4]:** If the request fails with an error before response status code was sent or received,
+**[4] `error.type`:** If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable)
or a component-specific low cardinality error identifier.
@@ -622,13 +622,13 @@ additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
-**[5]:** The value SHOULD be normalized to lowercase.
+**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
**[6]:** If not `http` and `network.protocol.version` is set.
-**[7]:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation.
+**[7] `url.template`:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation.
-**[8]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
+**[8] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
`error.type` 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.
@@ -685,7 +685,7 @@ This metric is optional.
| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [8] | `1.0`; `1.1`; `2`; `3` | `Recommended` |  |
| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | `Opt-In` |  |
-**[1]:** HTTP request method value SHOULD be "known" to the instrumentation.
+**[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@@ -700,11 +700,11 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
-**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used.
+**[2] `server.address`:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used.
-**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[3] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[4]:** If the request fails with an error before response status code was sent or received,
+**[4] `error.type`:** If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable)
or a component-specific low cardinality error identifier.
@@ -721,13 +721,13 @@ additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
-**[5]:** The value SHOULD be normalized to lowercase.
+**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
**[6]:** If not `http` and `network.protocol.version` is set.
-**[7]:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation.
+**[7] `url.template`:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation.
-**[8]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
+**[8] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
`error.type` 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.
@@ -779,11 +779,11 @@ This metric is optional.
| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [3] | `1.1`; `2` | `Recommended` |  |
| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | `Opt-In` |  |
-**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[1] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[2] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[3]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
+**[3] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
`http.connection.state` 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.
@@ -824,11 +824,11 @@ This metric is optional.
| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [3] | `1.1`; `2` | `Recommended` |  |
| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | `Opt-In` |  |
-**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[1] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[2] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[3]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
+**[3] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
@@ -860,13 +860,13 @@ This metric is optional.
| [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [4] | `GET`; `POST`; `HEAD` | `Recommended` |  |
| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | `Opt-In` |  |
-**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[1] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[2] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[3]:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation.
+**[3] `url.template`:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation.
-**[4]:** HTTP request method value SHOULD be "known" to the instrumentation.
+**[4] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md
index 9ee978c94f..56aadc55a8 100644
--- a/docs/http/http-spans.md
+++ b/docs/http/http-spans.md
@@ -163,7 +163,7 @@ For an HTTP client span, `SpanKind` MUST be `CLIENT`.
| [`url.template`](/docs/attributes-registry/url.md) | string | The low-cardinality template of an [absolute path reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.2). [14] | `/users/{id}`; `/users/:id`; `/users?id={id}` | `Opt-In` |  |
| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1`; `YourApp/1.0.0 grpc-java-okhttp/1.27.2` | `Opt-In` |  |
-**[1]:** HTTP request method value SHOULD be "known" to the instrumentation.
+**[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@@ -178,11 +178,11 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
-**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used.
+**[2] `server.address`:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used.
-**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[3] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[4]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment
+**[4] `url.full`:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment
is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless.
`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`.
@@ -206,7 +206,7 @@ This list is subject to change over time.
When a query string value is redacted, the query string key SHOULD still be preserved, e.g.
`https://www.example.com/path?color=blue&sig=REDACTED`.
-**[5]:** If the request fails with an error before response status code was sent or received,
+**[5] `error.type`:** If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable)
or a component-specific low cardinality error identifier.
@@ -225,25 +225,25 @@ If the request has completed successfully, instrumentations SHOULD NOT set `erro
**[6]:** If and only if it's different than `http.request.method`.
-**[7]:** The value SHOULD be normalized to lowercase.
+**[7] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
**[8]:** If not `http` and `network.protocol.version` is set.
-**[9]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other).
+**[9] `http.request.resend_count`:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other).
-**[10]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
+**[10] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
-**[11]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
+**[11] `http.request.header`:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
The `User-Agent` header is already captured in the `user_agent.original` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended.
The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers.
-**[12]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
+**[12] `http.response.header`:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
Users MAY explicitly configure instrumentations to capture them even though it is not recommended.
The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers.
-**[13]:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible.
+**[13] `network.transport`:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible.
-**[14]:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation.
+**[14] `url.template`:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation.
The following attributes can be important for making sampling decisions
and SHOULD be provided **at span creation time** (if provided at all):
@@ -405,7 +405,7 @@ For an HTTP server span, `SpanKind` MUST be `SERVER`.
| [`network.local.port`](/docs/attributes-registry/network.md) | int | Local socket port. Useful in case of a multi-port host. | `65123` | `Opt-In` |  |
| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [17] | `tcp`; `udp` | `Opt-In` |  |
-**[1]:** HTTP request method value SHOULD be "known" to the instrumentation.
+**[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@@ -420,11 +420,11 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
-**[2]:** Sensitive content provided in `url.path` SHOULD be scrubbed when instrumentations can identify it.
+**[2] `url.path`:** Sensitive content provided in `url.path` SHOULD be scrubbed when instrumentations can identify it.
-**[3]:** The scheme of the original client request, if known (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request.
+**[3] `url.scheme`:** The scheme of the original client request, if known (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request.
-**[4]:** If the request fails with an error before response status code was sent or received,
+**[4] `error.type`:** If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable)
or a component-specific low cardinality error identifier.
@@ -443,16 +443,16 @@ If the request has completed successfully, instrumentations SHOULD NOT set `erro
**[5]:** If and only if it's different than `http.request.method`.
-**[6]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
+**[6] `http.route`:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
-**[7]:** The value SHOULD be normalized to lowercase.
+**[7] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
**[8]:** If not `http` and `network.protocol.version` is set.
-**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
+**[9] `server.port`:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
-**[10]:** Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it.
+**[10] `url.query`:** Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it.
Query string values for the following keys SHOULD be redacted by default and replaced by the value `REDACTED`:
@@ -467,23 +467,23 @@ This list is subject to change over time.
When a query string value is redacted, the query string key SHOULD still be preserved, e.g.
`q=OpenTelemetry&sig=REDACTED`.
-**[11]:** The IP address of the original client behind all proxies, if known (e.g. from [Forwarded#for](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#for), [X-Forwarded-For](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-For), or a similar header). Otherwise, the immediate client peer address.
+**[11] `client.address`:** The IP address of the original client behind all proxies, if known (e.g. from [Forwarded#for](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#for), [X-Forwarded-For](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-For), or a similar header). Otherwise, the immediate client peer address.
-**[12]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
+**[12] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
-**[13]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
+**[13] `server.address`:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
-**[14]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available.
+**[14] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available.
-**[15]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
+**[15] `http.request.header`:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
The `User-Agent` header is already captured in the `user_agent.original` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended.
The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers.
-**[16]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
+**[16] `http.response.header`:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
Users MAY explicitly configure instrumentations to capture them even though it is not recommended.
The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers.
-**[17]:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible.
+**[17] `network.transport`:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible.
The following attributes can be important for making sampling decisions
and SHOULD be provided **at span creation time** (if provided at all):
diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md
index 9a0322cb90..2334c6a8d7 100644
--- a/docs/messaging/azure-messaging.md
+++ b/docs/messaging/azure-messaging.md
@@ -66,7 +66,7 @@ The following additional attributes are defined:
| [`messaging.servicebus.message.enqueued_time`](/docs/attributes-registry/messaging.md) | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | `Recommended` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Recommended` |  |
-**[1]:** The operation name SHOULD match one of the following values:
+**[1] `messaging.operation.name`:** The operation name SHOULD match one of the following values:
- sender operations: `send`, `schedule`, `cancel_scheduled`
- transaction operations: `create_transaction`, `commit_transaction`, `rollback_transaction`
@@ -77,7 +77,7 @@ The following additional attributes are defined:
If none of the above operation names apply, the attribute SHOULD be set
to the name of the client method in snake_case.
-**[2]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
+**[2] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
When `error.type` is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
@@ -97,22 +97,22 @@ it's RECOMMENDED to:
- Use a domain-specific attribute
- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
-**[3]:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
+**[3] `messaging.batch.message_count`:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
**[4]:** If the span describes an operation on a batch of messages.
-**[5]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
+**[5] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
**[6]:** If span describes operation on a single message or if the value applies to all messages in the batch.
-**[7]:** If a custom value is used, it MUST be of low cardinality.
+**[7] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality.
**[8]:** If delivery count is available and is bigger than 0.
-**[9]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
+**[9] `server.address`:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
-**[10]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[10] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
The following attributes can be important for making sampling decisions
and SHOULD be provided **at span creation time** (if provided at all):
@@ -182,7 +182,7 @@ The following additional attributes are defined:
| [`messaging.message.id`](/docs/attributes-registry/messaging.md) | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | `Recommended` If span describes operation on a single message. |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [9] | `80`; `8080`; `443` | `Recommended` |  |
-**[1]:** The operation name SHOULD match one of the following values:
+**[1] `messaging.operation.name`:** The operation name SHOULD match one of the following values:
- `send`
- `receive`
@@ -194,7 +194,7 @@ The following additional attributes are defined:
If none of the above operation names apply, the attribute SHOULD be set
to the name of the client method in snake_case.
-**[2]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
+**[2] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
When `error.type` is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
@@ -214,20 +214,20 @@ it's RECOMMENDED to:
- Use a domain-specific attribute
- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
-**[3]:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
+**[3] `messaging.batch.message_count`:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
**[4]:** If the span describes an operation on a batch of messages.
-**[5]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
+**[5] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
**[6]:** If span describes operation on a single message or if the value applies to all messages in the batch.
-**[7]:** If a custom value is used, it MUST be of low cardinality.
+**[7] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality.
-**[8]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
+**[8] `server.address`:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
-**[9]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[9] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
The following attributes can be important for making sampling decisions
and SHOULD be provided **at span creation time** (if provided at all):
diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md
index 84483b0d2c..e1fb577f63 100644
--- a/docs/messaging/gcp-pubsub.md
+++ b/docs/messaging/gcp-pubsub.md
@@ -65,7 +65,7 @@ For Google Cloud Pub/Sub, the following additional attributes are defined:
| [`messaging.message.id`](/docs/attributes-registry/messaging.md) | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | `Recommended` If span describes operation on a single message. |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [9] | `80`; `8080`; `443` | `Recommended` |  |
-**[1]:** The `messaging.operation.name` has the following list of well-known values in the context of Google Pub/Sub.
+**[1] `messaging.operation.name`:** The `messaging.operation.name` has the following list of well-known values in the context of Google Pub/Sub.
If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
- `ack` and `nack` for settlement operations
@@ -74,7 +74,7 @@ If one of them applies, then the respective value MUST be used; otherwise, a cus
- `subscribe` for operations that represent the time from after the message was received to when the message is acknowledged, negatively acknowledged, or expired.
- `create` and `receive` for [common messaging operations](/docs/messaging/messaging-spans.md#operation-types)
-**[2]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
+**[2] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
When `error.type` is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
@@ -94,20 +94,20 @@ it's RECOMMENDED to:
- Use a domain-specific attribute
- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
-**[3]:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
+**[3] `messaging.batch.message_count`:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
**[4]:** If the span describes an operation on a batch of messages.
-**[5]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
+**[5] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
**[6]:** If span describes operation on a single message or if the value applies to all messages in the batch.
-**[7]:** If a custom value is used, it MUST be of low cardinality.
+**[7] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality.
-**[8]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
+**[8] `server.address`:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
-**[9]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[9] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
The following attributes can be important for making sampling decisions
and SHOULD be provided **at span creation time** (if provided at all):
diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md
index 1e0797db8b..730ef38ad8 100644
--- a/docs/messaging/kafka.md
+++ b/docs/messaging/kafka.md
@@ -75,7 +75,7 @@ For Apache Kafka, the following additional attributes are defined:
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Recommended` |  |
| [`messaging.message.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. Only applicable for spans describing single message operations. [11] | `1439` | `Opt-In` |  |
-**[1]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
+**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
When `error.type` is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
@@ -95,26 +95,26 @@ it's RECOMMENDED to:
- Use a domain-specific attribute
- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
-**[2]:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
+**[2] `messaging.batch.message_count`:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
**[3]:** If the span describes an operation on a batch of messages.
-**[4]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
+**[4] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
**[5]:** If span describes operation on a single message or if the value applies to all messages in the batch.
**[6]:** If value is `true`. When missing, the value is assumed to be `false`.
-**[7]:** If a custom value is used, it MUST be of low cardinality.
+**[7] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality.
-**[8]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
+**[8] `server.address`:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
-**[9]:** If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value.
+**[9] `messaging.kafka.message.key`:** If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value.
-**[10]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[10] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[11]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed
+**[11] `messaging.message.body.size`:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed
body size should be used.
The following attributes can be important for making sampling decisions
diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md
index d083e0ec3e..82f492b809 100644
--- a/docs/messaging/messaging-metrics.md
+++ b/docs/messaging/messaging-metrics.md
@@ -83,9 +83,9 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
| [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | The identifier of the partition messages are sent to or received from, unique within the `messaging.destination.name`. | `1` | `Recommended` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Recommended` |  |
-**[1]:** The actual messaging system may differ from the one known by the client. For example, when using Kafka client libraries to communicate with Azure Event Hubs, the `messaging.system` is set to `kafka` based on the instrumentation's best knowledge.
+**[1] `messaging.system`:** The actual messaging system may differ from the one known by the client. For example, when using Kafka client libraries to communicate with Azure Event Hubs, the `messaging.system` is set to `kafka` based on the instrumentation's best knowledge.
-**[2]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
+**[2] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
When `error.type` is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
@@ -105,22 +105,22 @@ it's RECOMMENDED to:
- Use a domain-specific attribute
- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
-**[3]:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.consumer.group.name` is applicable and what it means in the context of that system.
+**[3] `messaging.consumer.group.name`:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.consumer.group.name` is applicable and what it means in the context of that system.
-**[4]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
+**[4] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
**[5]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated.
-**[6]:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.destination.subscription.name` is applicable and what it means in the context of that system.
+**[6] `messaging.destination.subscription.name`:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.destination.subscription.name` is applicable and what it means in the context of that system.
-**[7]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation.
+**[7] `messaging.destination.template`:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation.
-**[8]:** If a custom value is used, it MUST be of low cardinality.
+**[8] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality.
-**[9]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
+**[9] `server.address`:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
-**[10]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[10] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
`error.type` 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.
@@ -189,9 +189,9 @@ This metric is [required][MetricRequired].
| [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | The identifier of the partition messages are sent to or received from, unique within the `messaging.destination.name`. | `1` | `Recommended` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Recommended` |  |
-**[1]:** The actual messaging system may differ from the one known by the client. For example, when using Kafka client libraries to communicate with Azure Event Hubs, the `messaging.system` is set to `kafka` based on the instrumentation's best knowledge.
+**[1] `messaging.system`:** The actual messaging system may differ from the one known by the client. For example, when using Kafka client libraries to communicate with Azure Event Hubs, the `messaging.system` is set to `kafka` based on the instrumentation's best knowledge.
-**[2]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
+**[2] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
When `error.type` is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
@@ -211,16 +211,16 @@ it's RECOMMENDED to:
- Use a domain-specific attribute
- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
-**[3]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
+**[3] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
**[4]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated.
-**[5]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation.
+**[5] `messaging.destination.template`:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation.
-**[6]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
+**[6] `server.address`:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
-**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
`error.type` 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.
@@ -282,9 +282,9 @@ The metric SHOULD be reported once per message delivery. For example, if receivi
| [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | The identifier of the partition messages are sent to or received from, unique within the `messaging.destination.name`. | `1` | `Recommended` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [9] | `80`; `8080`; `443` | `Recommended` |  |
-**[1]:** The actual messaging system may differ from the one known by the client. For example, when using Kafka client libraries to communicate with Azure Event Hubs, the `messaging.system` is set to `kafka` based on the instrumentation's best knowledge.
+**[1] `messaging.system`:** The actual messaging system may differ from the one known by the client. For example, when using Kafka client libraries to communicate with Azure Event Hubs, the `messaging.system` is set to `kafka` based on the instrumentation's best knowledge.
-**[2]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
+**[2] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
When `error.type` is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
@@ -304,20 +304,20 @@ it's RECOMMENDED to:
- Use a domain-specific attribute
- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
-**[3]:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.consumer.group.name` is applicable and what it means in the context of that system.
+**[3] `messaging.consumer.group.name`:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.consumer.group.name` is applicable and what it means in the context of that system.
-**[4]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
+**[4] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
**[5]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated.
-**[6]:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.destination.subscription.name` is applicable and what it means in the context of that system.
+**[6] `messaging.destination.subscription.name`:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.destination.subscription.name` is applicable and what it means in the context of that system.
-**[7]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation.
+**[7] `messaging.destination.template`:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation.
-**[8]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
+**[8] `server.address`:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
-**[9]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[9] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
`error.type` 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.
@@ -382,9 +382,9 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
| [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | The identifier of the partition messages are sent to or received from, unique within the `messaging.destination.name`. | `1` | `Recommended` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [9] | `80`; `8080`; `443` | `Recommended` |  |
-**[1]:** The actual messaging system may differ from the one known by the client. For example, when using Kafka client libraries to communicate with Azure Event Hubs, the `messaging.system` is set to `kafka` based on the instrumentation's best knowledge.
+**[1] `messaging.system`:** The actual messaging system may differ from the one known by the client. For example, when using Kafka client libraries to communicate with Azure Event Hubs, the `messaging.system` is set to `kafka` based on the instrumentation's best knowledge.
-**[2]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
+**[2] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
When `error.type` is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
@@ -404,20 +404,20 @@ it's RECOMMENDED to:
- Use a domain-specific attribute
- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
-**[3]:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.consumer.group.name` is applicable and what it means in the context of that system.
+**[3] `messaging.consumer.group.name`:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.consumer.group.name` is applicable and what it means in the context of that system.
-**[4]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
+**[4] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
**[5]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated.
-**[6]:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.destination.subscription.name` is applicable and what it means in the context of that system.
+**[6] `messaging.destination.subscription.name`:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.destination.subscription.name` is applicable and what it means in the context of that system.
-**[7]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation.
+**[7] `messaging.destination.template`:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation.
-**[8]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
+**[8] `server.address`:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
-**[9]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[9] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
`error.type` 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/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md
index cb45f8b28c..6ef38a52d0 100644
--- a/docs/messaging/messaging-spans.md
+++ b/docs/messaging/messaging-spans.md
@@ -387,9 +387,9 @@ Messaging system-specific attributes MUST be defined in the corresponding `messa
| [`messaging.message.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. [17] | `1439` | `Opt-In` |  |
| [`messaging.message.envelope.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body and metadata in bytes. [18] | `2738` | `Opt-In` |  |
-**[1]:** The actual messaging system may differ from the one known by the client. For example, when using Kafka client libraries to communicate with Azure Event Hubs, the `messaging.system` is set to `kafka` based on the instrumentation's best knowledge.
+**[1] `messaging.system`:** The actual messaging system may differ from the one known by the client. For example, when using Kafka client libraries to communicate with Azure Event Hubs, the `messaging.system` is set to `kafka` based on the instrumentation's best knowledge.
-**[2]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
+**[2] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
When `error.type` is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
@@ -409,41 +409,41 @@ it's RECOMMENDED to:
- Use a domain-specific attribute
- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
-**[3]:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
+**[3] `messaging.batch.message_count`:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
**[4]:** If the span describes an operation on a batch of messages.
-**[5]:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.consumer.group.name` is applicable and what it means in the context of that system.
+**[5] `messaging.consumer.group.name`:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.consumer.group.name` is applicable and what it means in the context of that system.
**[6]:** If value is `true`. When missing, the value is assumed to be `false`.
-**[7]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
+**[7] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
**[8]:** If span describes operation on a single message or if the value applies to all messages in the batch.
-**[9]:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.destination.subscription.name` is applicable and what it means in the context of that system.
+**[9] `messaging.destination.subscription.name`:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.destination.subscription.name` is applicable and what it means in the context of that system.
-**[10]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation.
+**[10] `messaging.destination.template`:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation.
**[11]:** If available. Instrumentations MUST NOT use `messaging.destination.name` as template unless low-cardinality of destination name is guaranteed.
**[12]:** If value is `true`. When missing, the value is assumed to be `false`.
-**[13]:** If a custom value is used, it MUST be of low cardinality.
+**[13] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality.
-**[14]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
+**[14] `server.address`:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
-**[15]:** Semantic conventions for individual messaging systems SHOULD document whether `network.peer.*` attributes are applicable.
+**[15] `network.peer.address`:** Semantic conventions for individual messaging systems SHOULD document whether `network.peer.*` attributes are applicable.
Network peer address and port are important when the application interacts with individual intermediary nodes directly,
If a messaging operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
-**[16]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[16] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[17]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed
+**[17] `messaging.message.body.size`:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed
body size should be used.
-**[18]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed
+**[18] `messaging.message.envelope.size`:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed
size should be used.
The following attributes can be important for making sampling decisions
diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md
index c7d95f3a62..c07e597d8b 100644
--- a/docs/messaging/rabbitmq.md
+++ b/docs/messaging/rabbitmq.md
@@ -66,7 +66,7 @@ In RabbitMQ, the destination is defined by an *exchange* and a *routing key*.
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Recommended` |  |
| [`messaging.message.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. [8] | `1439` | `Opt-In` |  |
-**[1]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
+**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
When `error.type` is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
@@ -86,20 +86,20 @@ it's RECOMMENDED to:
- Use a domain-specific attribute
- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
-**[2]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
+**[2] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
**[3]:** If span describes operation on a single message or if the value applies to all messages in the batch.
-**[4]:** If a custom value is used, it MUST be of low cardinality.
+**[4] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality.
-**[5]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
+**[5] `server.address`:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
-**[6]:** If an operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
+**[6] `network.peer.address`:** If an operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
-**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[8]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed
+**[8] `messaging.message.body.size`:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed
body size should be used.
The following attributes can be important for making sampling decisions
diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md
index 8574b36f4b..04dca45b2c 100644
--- a/docs/messaging/rocketmq.md
+++ b/docs/messaging/rocketmq.md
@@ -71,7 +71,7 @@ Specific attributes for Apache RocketMQ are defined below.
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Recommended` |  |
| [`messaging.message.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. [11] | `1439` | `Opt-In` |  |
-**[1]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
+**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
When `error.type` is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
@@ -91,26 +91,26 @@ it's RECOMMENDED to:
- Use a domain-specific attribute
- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
-**[2]:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
+**[2] `messaging.batch.message_count`:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
**[3]:** If the span describes an operation on a batch of messages.
-**[4]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
+**[4] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
**[5]:** If span describes operation on a single message or if the value applies to all messages in the batch.
-**[6]:** If a custom value is used, it MUST be of low cardinality.
+**[6] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality.
**[7]:** If the message type is delay and delivery timestamp is not specified.
**[8]:** If the message type is delay and delay time level is not specified.
-**[9]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
+**[9] `server.address`:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
-**[10]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[10] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[11]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed
+**[11] `messaging.message.body.size`:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed
body size should be used.
The following attributes can be important for making sampling decisions
diff --git a/docs/object-stores/s3.md b/docs/object-stores/s3.md
index cb5a1ec093..4e5bec7952 100644
--- a/docs/object-stores/s3.md
+++ b/docs/object-stores/s3.md
@@ -31,21 +31,21 @@ described on this page.
| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [7] | `GetItem`; `PutItem` | `Recommended` |  |
| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [8] | `DynamoDB`; `S3` | `Recommended` |  |
-**[1]:** The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter.
+**[1] `aws.s3.bucket`:** The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter.
This applies to almost all S3 operations except `list-buckets`.
-**[2]:** The `copy_source` attribute applies to S3 copy operations and corresponds to the `--copy-source` parameter
+**[2] `aws.s3.copy_source`:** The `copy_source` attribute applies to S3 copy operations and corresponds to the `--copy-source` parameter
of the [copy-object operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html).
This applies in particular to the following operations:
- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html)
- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html)
-**[3]:** The `delete` attribute is only applicable to the [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) operation.
+**[3] `aws.s3.delete`:** The `delete` attribute is only applicable to the [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) operation.
The `delete` attribute corresponds to the `--delete` parameter of the
[delete-objects operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-objects.html).
-**[4]:** The `key` attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter.
+**[4] `aws.s3.key`:** The `key` attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter.
This applies in particular to the following operations:
- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html)
@@ -62,12 +62,12 @@ This applies in particular to the following operations:
- [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html)
-**[5]:** The `part_number` attribute is only applicable to the [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
+**[5] `aws.s3.part_number`:** The `part_number` attribute is only applicable to the [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
and [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) operations.
The `part_number` attribute corresponds to the `--part-number` parameter of the
[upload-part operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html).
-**[6]:** The `upload_id` attribute applies to S3 multipart-upload operations and corresponds to the `--upload-id` parameter
+**[6] `aws.s3.upload_id`:** The `upload_id` attribute applies to S3 multipart-upload operations and corresponds to the `--upload-id` parameter
of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) multipart operations.
This applies in particular to the following operations:
@@ -77,9 +77,9 @@ This applies in particular to the following operations:
- [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html)
-**[7]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[7] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[8]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[8] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`rpc.system` 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/docs/resource/README.md b/docs/resource/README.md
index 2ae0e3520c..9e10b1f651 100644
--- a/docs/resource/README.md
+++ b/docs/resource/README.md
@@ -93,9 +93,9 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet
| [`service.namespace`](/docs/attributes-registry/service.md) | string | A namespace for `service.name`. [3] | `Shop` | `Recommended` |  |
| [`service.version`](/docs/attributes-registry/service.md) | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | `Recommended` |  |
-**[1]:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`.
+**[1] `service.name`:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`.
-**[2]:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words
+**[2] `service.instance.id`:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words
`service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to
distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled
service).
@@ -122,7 +122,7 @@ However, Collectors can set the `service.instance.id` if they can unambiguously
for that telemetry. This is typically the case for scraping receivers, as they know the target address and
port.
-**[3]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace.
+**[3] `service.namespace`:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace.
@@ -165,7 +165,7 @@ service.name = Shop.shoppingcart
| [`telemetry.sdk.name`](/docs/attributes-registry/telemetry.md) | string | The name of the telemetry SDK as defined above. [1] | `opentelemetry` | `Required` |  |
| [`telemetry.sdk.version`](/docs/attributes-registry/telemetry.md) | string | The version string of the telemetry SDK. | `1.2.3` | `Required` |  |
-**[1]:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`.
+**[1] `telemetry.sdk.name`:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`.
If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the
`telemetry.sdk.name` attribute to the fully-qualified class or module name of this SDK's main entry point
or another suitable identifier depending on the language.
@@ -215,7 +215,7 @@ All custom identifiers SHOULD be stable across different versions of an implemen
| [`telemetry.distro.name`](/docs/attributes-registry/telemetry.md) | string | The name of the auto instrumentation agent or distribution, if used. [1] | `parts-unlimited-java` | `Recommended` |  |
| [`telemetry.distro.version`](/docs/attributes-registry/telemetry.md) | string | The version string of the auto instrumentation agent or distribution, if used. | `1.2.3` | `Recommended` |  |
-**[1]:** Official auto instrumentation agents and distributions SHOULD set the `telemetry.distro.name` attribute to
+**[1] `telemetry.distro.name`:** Official auto instrumentation agents and distributions SHOULD set the `telemetry.distro.name` attribute to
a string starting with `opentelemetry-`, e.g. `opentelemetry-java-instrumentation`.
diff --git a/docs/resource/browser.md b/docs/resource/browser.md
index 02a356a42e..0805b8c5c6 100644
--- a/docs/resource/browser.md
+++ b/docs/resource/browser.md
@@ -22,16 +22,16 @@
| [`browser.platform`](/docs/attributes-registry/browser.md) | string | The platform on which the browser is running [4] | `Windows`; `macOS`; `Android` | `Recommended` |  |
| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string provided by the browser [5] | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36` | `Recommended` |  |
-**[1]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`).
+**[1] `browser.brands`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`).
-**[2]:** This value is intended to be taken from the Navigator API `navigator.language`.
+**[2] `browser.language`:** This value is intended to be taken from the Navigator API `navigator.language`.
-**[3]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.mobile`). If unavailable, this attribute SHOULD be left unset.
+**[3] `browser.mobile`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.mobile`). If unavailable, this attribute SHOULD be left unset.
-**[4]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent.
+**[4] `browser.platform`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent.
The list of possible values is defined in the [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). Note that some (but not all) of these values can overlap with values in the [`os.type` and `os.name` attributes](./os.md). However, for consistency, the values in the `browser.platform` attribute should capture the exact value that the user agent provides.
-**[5]:** The user-agent value SHOULD be provided only from browsers that do not have a mechanism to retrieve brands and platform individually from the User-Agent Client Hints API. To retrieve the value, the legacy `navigator.userAgent` API can be used.
+**[5] `user_agent.original`:** The user-agent value SHOULD be provided only from browsers that do not have a mechanism to retrieve brands and platform individually from the User-Agent Client Hints API. To retrieve the value, the legacy `navigator.userAgent` API can be used.
diff --git a/docs/resource/cloud-provider/aws/logs.md b/docs/resource/cloud-provider/aws/logs.md
index 2011ff2d8c..d159aad5a6 100644
--- a/docs/resource/cloud-provider/aws/logs.md
+++ b/docs/resource/cloud-provider/aws/logs.md
@@ -21,11 +21,11 @@
| [`aws.log.stream.arns`](/docs/attributes-registry/aws.md) | string[] | The ARN(s) of the AWS log stream(s). [3] | `["arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:log-stream:logs/main/10838bed-421f-43ef-870a-f43feacbbb5b"]` | `Recommended` |  |
| [`aws.log.stream.names`](/docs/attributes-registry/aws.md) | string[] | The name(s) of the AWS log stream(s) an application is writing to. | `["logs/main/10838bed-421f-43ef-870a-f43feacbbb5b"]` | `Recommended` |  |
-**[1]:** See the [log group ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format).
+**[1] `aws.log.group.arns`:** See the [log group ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format).
-**[2]:** Multiple log groups must be supported for cases like multi-container applications, where a single application has sidecar containers, and each write to their own log group.
+**[2] `aws.log.group.names`:** Multiple log groups must be supported for cases like multi-container applications, where a single application has sidecar containers, and each write to their own log group.
-**[3]:** See the [log stream ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). One log group can contain several log streams, so these ARNs necessarily identify both a log group and a log stream.
+**[3] `aws.log.stream.arns`:** See the [log stream ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). One log group can contain several log streams, so these ARNs necessarily identify both a log group and a log stream.
diff --git a/docs/resource/cloud.md b/docs/resource/cloud.md
index 13eeaec65f..bda2c91c75 100644
--- a/docs/resource/cloud.md
+++ b/docs/resource/cloud.md
@@ -23,13 +23,13 @@
| [`cloud.region`](/docs/attributes-registry/cloud.md) | string | The geographical region the resource is running. [3] | `us-central1`; `us-east-1` | `Recommended` |  |
| [`cloud.resource_id`](/docs/attributes-registry/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/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) [4] | `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]:** Availability zones are called "zones" on Alibaba Cloud and Google Cloud.
+**[1] `cloud.availability_zone`:** Availability zones are called "zones" on Alibaba Cloud and Google Cloud.
-**[2]:** The prefix of the service SHOULD match the one specified in `cloud.provider`.
+**[2] `cloud.platform`:** The prefix of the service SHOULD match the one specified in `cloud.provider`.
-**[3]:** 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/global-infrastructure/geographies/), [Google Cloud regions](https://cloud.google.com/about/locations), or [Tencent Cloud regions](https://www.tencentcloud.com/document/product/213/6091).
+**[3] `cloud.region`:** 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/global-infrastructure/geographies/), [Google Cloud regions](https://cloud.google.com/about/locations), or [Tencent Cloud regions](https://www.tencentcloud.com/document/product/213/6091).
-**[4]:** On some cloud providers, it may not be possible to determine the full ID at startup,
+**[4] `cloud.resource_id`:** 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.
diff --git a/docs/resource/cloudfoundry.md b/docs/resource/cloudfoundry.md
index c789076aa2..71f363de8d 100644
--- a/docs/resource/cloudfoundry.md
+++ b/docs/resource/cloudfoundry.md
@@ -41,11 +41,11 @@ They align with the Bosh deployment tool of CloudFoundry.
| [`cloudfoundry.org.id`](/docs/attributes-registry/cloudfoundry.md) | string | The guid of the CloudFoundry org the application is running in. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | `Recommended` |  |
| [`cloudfoundry.org.name`](/docs/attributes-registry/cloudfoundry.md) | string | The name of the CloudFoundry organization the app is running in. [2] | `my-org-name` | `Recommended` |  |
-**[1]:** Application instrumentation should use the value from environment
+**[1] `cloudfoundry.org.id`:** Application instrumentation should use the value from environment
variable `VCAP_APPLICATION.org_id`. This is the same value as
reported by `cf org --guid`.
-**[2]:** Application instrumentation should use the value from environment
+**[2] `cloudfoundry.org.name`:** Application instrumentation should use the value from environment
variable `VCAP_APPLICATION.org_name`. This is the same value as
reported by `cf orgs`.
@@ -75,11 +75,11 @@ reported by `cf orgs`.
| [`cloudfoundry.space.id`](/docs/attributes-registry/cloudfoundry.md) | string | The guid of the CloudFoundry space the application is running in. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | `Recommended` |  |
| [`cloudfoundry.space.name`](/docs/attributes-registry/cloudfoundry.md) | string | The name of the CloudFoundry space the application is running in. [2] | `my-space-name` | `Recommended` |  |
-**[1]:** Application instrumentation should use the value from environment
+**[1] `cloudfoundry.space.id`:** Application instrumentation should use the value from environment
variable `VCAP_APPLICATION.space_id`. This is the same value as
reported by `cf space --guid`.
-**[2]:** Application instrumentation should use the value from environment
+**[2] `cloudfoundry.space.name`:** Application instrumentation should use the value from environment
variable `VCAP_APPLICATION.space_name`. This is the same value as
reported by `cf spaces`.
@@ -109,11 +109,11 @@ reported by `cf spaces`.
| [`cloudfoundry.app.id`](/docs/attributes-registry/cloudfoundry.md) | string | The guid of the application. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | `Recommended` |  |
| [`cloudfoundry.app.name`](/docs/attributes-registry/cloudfoundry.md) | string | The name of the application. [2] | `my-app-name` | `Recommended` |  |
-**[1]:** Application instrumentation should use the value from environment
+**[1] `cloudfoundry.app.id`:** Application instrumentation should use the value from environment
variable `VCAP_APPLICATION.application_id`. This is the same value as
reported by `cf app --guid`.
-**[2]:** Application instrumentation should use the value from environment
+**[2] `cloudfoundry.app.name`:** Application instrumentation should use the value from environment
variable `VCAP_APPLICATION.application_name`. This is the same value
as reported by `cf apps`.
@@ -143,12 +143,12 @@ as reported by `cf apps`.
| [`cloudfoundry.process.id`](/docs/attributes-registry/cloudfoundry.md) | string | The UID identifying the process. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | `Recommended` |  |
| [`cloudfoundry.process.type`](/docs/attributes-registry/cloudfoundry.md) | string | The type of process. [2] | `web` | `Recommended` |  |
-**[1]:** Application instrumentation should use the value from environment
+**[1] `cloudfoundry.process.id`:** Application instrumentation should use the value from environment
variable `VCAP_APPLICATION.process_id`. It is supposed to be equal to
`VCAP_APPLICATION.app_id` for applications deployed to the runtime.
For system components, this could be the actual PID.
-**[2]:** CloudFoundry applications can consist of multiple jobs. Usually the
+**[2] `cloudfoundry.process.type`:** CloudFoundry applications can consist of multiple jobs. Usually the
main process will be of type `web`. There can be additional background
tasks or side-cars with different process types.
@@ -178,7 +178,7 @@ tasks or side-cars with different process types.
| [`cloudfoundry.system.id`](/docs/attributes-registry/cloudfoundry.md) | string | A guid or another name describing the event source. [1] | `cf/gorouter` | `Recommended` |  |
| [`cloudfoundry.system.instance.id`](/docs/attributes-registry/cloudfoundry.md) | string | A guid describing the concrete instance of the event source. [2] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | `Recommended` |  |
-**[1]:** CloudFoundry defines the `source_id` in the [Loggregator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope).
+**[1] `cloudfoundry.system.id`:** CloudFoundry defines the `source_id` in the [Loggregator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope).
It is used for logs and metrics emitted by CloudFoundry. It is
supposed to contain the component name, e.g. "gorouter", for
CloudFoundry components.
@@ -188,7 +188,7 @@ When system components are instrumented, values from the
should be used. The `system.id` should be set to
`spec.deployment/spec.name`.
-**[2]:** CloudFoundry defines the `instance_id` in the [Loggregator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope).
+**[2] `cloudfoundry.system.instance.id`:** CloudFoundry defines the `instance_id` in the [Loggregator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope).
It is used for logs and metrics emitted by CloudFoundry. It is
supposed to contain the vm id for CloudFoundry components.
diff --git a/docs/resource/container.md b/docs/resource/container.md
index 89ffe0b9b4..9064352aba 100644
--- a/docs/resource/container.md
+++ b/docs/resource/container.md
@@ -29,16 +29,16 @@
| [`container.command_args`](/docs/attributes-registry/container.md) | string[] | All the command arguments (including the command/executable itself) run by the container. | `["otelcontribcol", "--config", "config.yaml"]` | `Opt-In` |  |
| [`container.command_line`](/docs/attributes-registry/container.md) | string | The full command run by the container as a single string representing the full command. | `otelcontribcol --config config.yaml` | `Opt-In` |  |
-**[1]:** Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) endpoint.
+**[1] `container.image.id`:** Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) endpoint.
K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`.
The ID is assigned by the container runtime and can vary in different environments. Consider using `oci.manifest.digest` if it is important to identify the same image in different environments/runtimes.
-**[2]:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field.
+**[2] `container.image.repo_digests`:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field.
-**[3]:** Follows [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md), and specifically the [Digest property](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests).
+**[3] `oci.manifest.digest`:** Follows [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md), and specifically the [Digest property](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests).
An example can be found in [Example Image Manifest](https://docs.docker.com/registry/spec/manifest-v2-2/#example-image-manifest).
-**[4]:** If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage.
+**[4] `container.command`:** If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage.
diff --git a/docs/resource/deployment-environment.md b/docs/resource/deployment-environment.md
index 8499e2cf08..d6ea51ecdf 100644
--- a/docs/resource/deployment-environment.md
+++ b/docs/resource/deployment-environment.md
@@ -18,7 +18,7 @@
|---|---|---|---|---|---|
| [`deployment.environment.name`](/docs/attributes-registry/deployment.md) | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | `Recommended` |  |
-**[1]:** `deployment.environment.name` does not affect the uniqueness constraints defined through
+**[1] `deployment.environment.name`:** `deployment.environment.name` does not affect the uniqueness constraints defined through
the `service.namespace`, `service.name` and `service.instance.id` resource attributes.
This implies that resources carrying the following attribute combinations MUST be
considered to be identifying the same service:
diff --git a/docs/resource/device.md b/docs/resource/device.md
index ae60eb783c..1f5be497cd 100644
--- a/docs/resource/device.md
+++ b/docs/resource/device.md
@@ -21,13 +21,13 @@
| [`device.model.identifier`](/docs/attributes-registry/device.md) | string | The model identifier for the device [3] | `iPhone3,4`; `SM-G920F` | `Recommended` |  |
| [`device.model.name`](/docs/attributes-registry/device.md) | string | The marketing name for the device model [4] | `iPhone 6s Plus`; `Samsung Galaxy S6` | `Recommended` |  |
-**[1]:** The device identifier MUST only be defined using the values outlined below. This value is not an advertising identifier and MUST NOT be used as such. On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) on best practices and exact implementation details. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence.
+**[1] `device.id`:** The device identifier MUST only be defined using the values outlined below. This value is not an advertising identifier and MUST NOT be used as such. On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) on best practices and exact implementation details. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence.
-**[2]:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`.
+**[2] `device.manufacturer`:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`.
-**[3]:** It's recommended this value represents a machine-readable version of the model identifier rather than the market or consumer-friendly name of the device.
+**[3] `device.model.identifier`:** It's recommended this value represents a machine-readable version of the model identifier rather than the market or consumer-friendly name of the device.
-**[4]:** It's recommended this value represents a human-readable version of the device model rather than a machine-readable alternative.
+**[4] `device.model.name`:** It's recommended this value represents a human-readable version of the device model rather than a machine-readable alternative.
diff --git a/docs/resource/faas.md b/docs/resource/faas.md
index 2f8ecd5711..0bd52a608e 100644
--- a/docs/resource/faas.md
+++ b/docs/resource/faas.md
@@ -29,7 +29,7 @@ See also:
| [`faas.max_memory`](/docs/attributes-registry/faas.md) | int | The amount of memory available to the serverless function converted to Bytes. [4] | `134217728` | `Recommended` |  |
| [`faas.version`](/docs/attributes-registry/faas.md) | string | The immutable version of the function being executed. [5] | `26`; `pinkfroid-00002` | `Recommended` |  |
-**[1]:** This is the name of the function as configured/deployed on the FaaS
+**[1] `faas.name`:** This is the name of the function as configured/deployed on the FaaS
platform and is usually different from the name of the callback
function (which may be stored in the
[`code.namespace`/`code.function`](/docs/general/attributes.md#source-code-attributes)
@@ -46,7 +46,7 @@ definition of function name MUST be used for this attribute
app can host multiple functions that would usually share
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,
+**[2] `cloud.resource_id`:** 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.
@@ -64,11 +64,11 @@ The following well-known definitions MUST be used if you set this attribute and
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]:** - **AWS Lambda:** Use the (full) log stream name.
+**[3] `faas.instance`:** - **AWS Lambda:** Use the (full) log stream name.
-**[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).
+**[4] `faas.max_memory`:** 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).
-**[5]:** Depending on the cloud provider and platform, use:
+**[5] `faas.version`:** 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).
diff --git a/docs/resource/host.md b/docs/resource/host.md
index fe08de147b..7b473376c1 100644
--- a/docs/resource/host.md
+++ b/docs/resource/host.md
@@ -29,7 +29,7 @@ To report host metrics, the `system.*` namespace SHOULD be used.
| [`host.ip`](/docs/attributes-registry/host.md) | string[] | Available IP addresses of the host, excluding loopback interfaces. [2] | `["192.168.1.140", "fe80::abc2:4a28:737a:609e"]` | `Opt-In` |  |
| [`host.mac`](/docs/attributes-registry/host.md) | string[] | Available MAC addresses of the host, excluding loopback interfaces. [3] | `["AC-DE-48-23-45-67", "AC-DE-48-23-45-67-01-9F"]` | `Opt-In` |  |
-**[1]:** Collecting `host.id` from non-containerized systems
+**[1] `host.id`:** Collecting `host.id` from non-containerized systems
**Non-privileged Machine ID Lookup**
@@ -55,9 +55,9 @@ detector implementations MUST not collect `host.id` from privileged sources. If
privileged lookup of `host.id` is required, the value should be injected via the
`OTEL_RESOURCE_ATTRIBUTES` environment variable.
-**[2]:** IPv4 Addresses MUST be specified in dotted-quad notation. IPv6 addresses MUST be specified in the [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952.html) format.
+**[2] `host.ip`:** IPv4 Addresses MUST be specified in dotted-quad notation. IPv6 addresses MUST be specified in the [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952.html) format.
-**[3]:** MAC Addresses MUST be represented in [IEEE RA hexadecimal form](https://standards.ieee.org/wp-content/uploads/import/documents/tutorials/eui.pdf): as hyphen-separated octets in uppercase hexadecimal form from most to least significant.
+**[3] `host.mac`:** MAC Addresses MUST be represented in [IEEE RA hexadecimal form](https://standards.ieee.org/wp-content/uploads/import/documents/tutorials/eui.pdf): as hyphen-separated octets in uppercase hexadecimal form from most to least significant.
`host.arch` 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.
@@ -102,7 +102,7 @@ privileged lookup of `host.id` is required, the value should be injected via the
| [`host.cpu.stepping`](/docs/attributes-registry/host.md) | string | Stepping or core revisions. | `1`; `r1p1` | `Opt-In` |  |
| [`host.cpu.vendor.id`](/docs/attributes-registry/host.md) | string | Processor manufacturer identifier. A maximum 12-character string. [1] | `GenuineIntel` | `Opt-In` |  |
-**[1]:** [CPUID](https://wiki.osdev.org/CPUID) command returns the vendor ID string in EBX, EDX and ECX registers. Writing these to memory in this order results in a 12-character string.
+**[1] `host.cpu.vendor.id`:** [CPUID](https://wiki.osdev.org/CPUID) command returns the vendor ID string in EBX, EDX and ECX registers. Writing these to memory in this order results in a 12-character string.
diff --git a/docs/resource/k8s.md b/docs/resource/k8s.md
index 64d01eb13a..c06e680657 100644
--- a/docs/resource/k8s.md
+++ b/docs/resource/k8s.md
@@ -36,7 +36,7 @@ Kubernetes object, but "name" is usually more user friendly so can be also set.
| [`k8s.cluster.name`](/docs/attributes-registry/k8s.md) | string | The name of the cluster. | `opentelemetry-cluster` | `Recommended` |  |
| [`k8s.cluster.uid`](/docs/attributes-registry/k8s.md) | string | A pseudo-ID for the cluster, set to the UID of the `kube-system` namespace. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | `Recommended` |  |
-**[1]:** K8s doesn't have support for obtaining a cluster ID. If this is ever
+**[1] `k8s.cluster.uid`:** K8s doesn't have support for obtaining a cluster ID. If this is ever
added, we will recommend collecting the `k8s.cluster.uid` through the
official APIs. In the meantime, we are able to use the `uid` of the
`kube-system` namespace as a proxy for cluster ID. Read on for the
diff --git a/docs/resource/os.md b/docs/resource/os.md
index 6a5c2c16c0..c815cd687e 100644
--- a/docs/resource/os.md
+++ b/docs/resource/os.md
@@ -24,7 +24,7 @@ In case of virtualized environments, this is the operating system as it is obser
| [`os.name`](/docs/attributes-registry/os.md) | string | Human readable operating system name. | `iOS`; `Android`; `Ubuntu` | `Recommended` |  |
| [`os.version`](/docs/attributes-registry/os.md) | string | The version string of the operating system as defined in [Version Attributes](/docs/resource/README.md#version-attributes). | `14.2.1`; `18.04.1` | `Recommended` |  |
-**[1]:** `build_id` values SHOULD be obtained from the following sources:
+**[1] `os.build_id`:** `build_id` values SHOULD be obtained from the following sources:
| OS | Primary | Fallback |
| ------- | ------- | ------- |
diff --git a/docs/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md
index 062cc07fd7..ef1e205238 100644
--- a/docs/rpc/connect-rpc.md
+++ b/docs/rpc/connect-rpc.md
@@ -31,9 +31,9 @@ Below is a table of attributes that SHOULD be included on client and server Conn
**[1]:** If response is not successful and if error code available.
-**[2]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
+**[2] `rpc.connect_rpc.request.metadata`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
-**[3]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
+**[3] `rpc.connect_rpc.response.metadata`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
`rpc.connect_rpc.error_code` 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/docs/rpc/grpc.md b/docs/rpc/grpc.md
index f5e4a92a0c..043feed182 100644
--- a/docs/rpc/grpc.md
+++ b/docs/rpc/grpc.md
@@ -29,9 +29,9 @@ Below is a table of attributes that SHOULD be included on client and server gRPC
| [`rpc.grpc.request.metadata.`](/docs/attributes-registry/rpc.md) | string[] | gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [1] | `rpc.grpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]` | `Opt-In` |  |
| [`rpc.grpc.response.metadata.`](/docs/attributes-registry/rpc.md) | string[] | gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [2] | `rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]` | `Opt-In` |  |
-**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
+**[1] `rpc.grpc.request.metadata`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
-**[2]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
+**[2] `rpc.grpc.response.metadata`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
`rpc.grpc.status_code` 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/docs/rpc/json-rpc.md b/docs/rpc/json-rpc.md
index 41e1458fb4..02ce236b64 100644
--- a/docs/rpc/json-rpc.md
+++ b/docs/rpc/json-rpc.md
@@ -29,7 +29,7 @@ described on this page.
| [`rpc.jsonrpc.error_message`](/docs/attributes-registry/rpc.md) | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | `Recommended` |  |
| [`rpc.jsonrpc.request_id`](/docs/attributes-registry/rpc.md) | string | `id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. | `10`; `request-7`; `` | `Recommended` |  |
-**[1]:** This is always required for jsonrpc. See the note in the general RPC conventions for more information.
+**[1] `rpc.method`:** This is always required for jsonrpc. See the note in the general RPC conventions for more information.
diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md
index ad2653f792..17ecbc8359 100644
--- a/docs/rpc/rpc-metrics.md
+++ b/docs/rpc/rpc-metrics.md
@@ -333,21 +333,21 @@ measurements.
| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Recommended` |  |
-**[1]:** The value SHOULD be normalized to lowercase.
+**[1] `network.transport`:** The value SHOULD be normalized to lowercase.
Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport. For example
different processes could be listening on TCP port 12345 and UDP port 12345.
-**[2]:** The value SHOULD be normalized to lowercase.
+**[2] `network.type`:** The value SHOULD be normalized to lowercase.
-**[3]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[3] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[4]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[4] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
-**[5]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[5] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
`network.transport` 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/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md
index f04c37a118..9e14b1d8dd 100644
--- a/docs/rpc/rpc-spans.md
+++ b/docs/rpc/rpc-spans.md
@@ -114,23 +114,23 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service
| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [6] | `exampleMethod` | `Recommended` |  |
| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [7] | `myservice.EchoService` | `Recommended` |  |
-**[1]:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component.
+**[1] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component.
-**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[2] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[3]:** if the port is supported by the network transport used for communication.
-**[4]:** The value SHOULD be normalized to lowercase.
+**[4] `network.transport`:** The value SHOULD be normalized to lowercase.
Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport. For example
different processes could be listening on TCP port 12345 and UDP port 12345.
-**[5]:** The value SHOULD be normalized to lowercase.
+**[5] `network.type`:** The value SHOULD be normalized to lowercase.
-**[6]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[6] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[7]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[7] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`network.transport` 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.
@@ -187,27 +187,27 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [8] | `exampleMethod` | `Recommended` |  |
| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [9] | `myservice.EchoService` | `Recommended` |  |
-**[1]:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component.
+**[1] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component.
-**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[2] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[3]:** if the port is supported by the network transport used for communication.
-**[4]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available.
+**[4] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available.
-**[5]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available.
+**[5] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available.
-**[6]:** The value SHOULD be normalized to lowercase.
+**[6] `network.transport`:** The value SHOULD be normalized to lowercase.
Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport. For example
different processes could be listening on TCP port 12345 and UDP port 12345.
-**[7]:** The value SHOULD be normalized to lowercase.
+**[7] `network.type`:** The value SHOULD be normalized to lowercase.
-**[8]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[8] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
-**[9]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+**[9] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
`network.transport` 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.
@@ -267,7 +267,7 @@ In the lifetime of an RPC stream, an event for each message sent/received on cli
| [`rpc.message.type`](/docs/attributes-registry/rpc.md) | string | Whether this is a received or sent message. | `SENT`; `RECEIVED` | `Recommended` |  |
| [`rpc.message.uncompressed_size`](/docs/attributes-registry/rpc.md) | int | Uncompressed size of the message in bytes. | | `Recommended` |  |
-**[1]:** This way we guarantee that the values will be consistent between different implementations.
+**[1] `rpc.message.id`:** This way we guarantee that the values will be consistent between different implementations.
`rpc.message.type` 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/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md
index 0e5f6619a9..57e28e749a 100644
--- a/docs/runtime/jvm-metrics.md
+++ b/docs/runtime/jvm-metrics.md
@@ -66,7 +66,7 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle
| [`jvm.memory.pool.name`](/docs/attributes-registry/jvm.md) | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | `Recommended` |  |
| [`jvm.memory.type`](/docs/attributes-registry/jvm.md) | string | The type of memory. | `heap`; `non_heap` | `Recommended` |  |
-**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
+**[1] `jvm.memory.pool.name`:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
`jvm.memory.type` 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.
@@ -101,7 +101,7 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle
| [`jvm.memory.pool.name`](/docs/attributes-registry/jvm.md) | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | `Recommended` |  |
| [`jvm.memory.type`](/docs/attributes-registry/jvm.md) | string | The type of memory. | `heap`; `non_heap` | `Recommended` |  |
-**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
+**[1] `jvm.memory.pool.name`:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
`jvm.memory.type` 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.
@@ -136,7 +136,7 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle
| [`jvm.memory.pool.name`](/docs/attributes-registry/jvm.md) | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | `Recommended` |  |
| [`jvm.memory.type`](/docs/attributes-registry/jvm.md) | string | The type of memory. | `heap`; `non_heap` | `Recommended` |  |
-**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
+**[1] `jvm.memory.pool.name`:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
`jvm.memory.type` 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.
@@ -171,7 +171,7 @@ This metric is obtained from [`MemoryPoolMXBean#getCollectionUsage()`](https://d
| [`jvm.memory.pool.name`](/docs/attributes-registry/jvm.md) | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | `Recommended` |  |
| [`jvm.memory.type`](/docs/attributes-registry/jvm.md) | string | The type of memory. | `heap`; `non_heap` | `Recommended` |  |
-**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
+**[1] `jvm.memory.pool.name`:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
`jvm.memory.type` 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.
@@ -217,9 +217,9 @@ of `[ 0.01, 0.1, 1, 10 ]`.
| [`jvm.gc.action`](/docs/attributes-registry/jvm.md) | string | Name of the garbage collector action. [1] | `end of minor GC`; `end of major GC` | `Recommended` |  |
| [`jvm.gc.name`](/docs/attributes-registry/jvm.md) | string | Name of the garbage collector. [2] | `G1 Young Generation`; `G1 Old Generation` | `Recommended` |  |
-**[1]:** Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()).
+**[1] `jvm.gc.action`:** Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()).
-**[2]:** Garbage collector name is generally obtained via [GarbageCollectionNotificationInfo#getGcName()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcName()).
+**[2] `jvm.gc.name`:** Garbage collector name is generally obtained via [GarbageCollectionNotificationInfo#getGcName()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcName()).
@@ -448,7 +448,7 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle
| [`jvm.memory.pool.name`](/docs/attributes-registry/jvm.md) | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | `Recommended` |  |
| [`jvm.memory.type`](/docs/attributes-registry/jvm.md) | string | The type of memory. | `heap`; `non_heap` | `Recommended` |  |
-**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
+**[1] `jvm.memory.pool.name`:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
`jvm.memory.type` 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.
@@ -529,7 +529,7 @@ This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.o
|---|---|---|---|---|---|
| [`jvm.buffer.pool.name`](/docs/attributes-registry/jvm.md) | string | Name of the buffer pool. [1] | `mapped`; `direct` | `Recommended` |  |
-**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()).
+**[1] `jvm.buffer.pool.name`:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()).
@@ -556,7 +556,7 @@ This metric is obtained from [`BufferPoolMXBean#getTotalCapacity()`](https://doc
|---|---|---|---|---|---|
| [`jvm.buffer.pool.name`](/docs/attributes-registry/jvm.md) | string | Name of the buffer pool. [1] | `mapped`; `direct` | `Recommended` |  |
-**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()).
+**[1] `jvm.buffer.pool.name`:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()).
@@ -583,7 +583,7 @@ This metric is obtained from [`BufferPoolMXBean#getCount()`](https://docs.oracle
|---|---|---|---|---|---|
| [`jvm.buffer.pool.name`](/docs/attributes-registry/jvm.md) | string | Name of the buffer pool. [1] | `mapped`; `direct` | `Recommended` |  |
-**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()).
+**[1] `jvm.buffer.pool.name`:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()).
diff --git a/docs/runtime/v8js-metrics.md b/docs/runtime/v8js-metrics.md
index 07a5efc36c..6d00bb9c64 100644
--- a/docs/runtime/v8js-metrics.md
+++ b/docs/runtime/v8js-metrics.md
@@ -87,7 +87,7 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`v8js.heap.space.name`](/docs/attributes-registry/v8js.md) | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | `Required` |  |
-**[1]:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics)
+**[1] `v8js.heap.space.name`:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics)
`v8js.heap.space.name` 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.
@@ -125,7 +125,7 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`v8js.heap.space.name`](/docs/attributes-registry/v8js.md) | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | `Required` |  |
-**[1]:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics)
+**[1] `v8js.heap.space.name`:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics)
`v8js.heap.space.name` 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.
@@ -163,7 +163,7 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`v8js.heap.space.name`](/docs/attributes-registry/v8js.md) | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | `Required` |  |
-**[1]:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics)
+**[1] `v8js.heap.space.name`:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics)
`v8js.heap.space.name` 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.
@@ -201,7 +201,7 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`v8js.heap.space.name`](/docs/attributes-registry/v8js.md) | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | `Required` |  |
-**[1]:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics)
+**[1] `v8js.heap.space.name`:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics)
`v8js.heap.space.name` 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/docs/system/container-metrics.md b/docs/system/container-metrics.md
index ac2df5e984..3ddf5a1957 100644
--- a/docs/system/container-metrics.md
+++ b/docs/system/container-metrics.md
@@ -33,7 +33,7 @@ This metric is [opt-in][MetricOptIn].
|---|---|---|---|---|---|
| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A container's CPU metric SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` | `Conditionally Required` [2] |  |
-**[1]:** Following states SHOULD be used: `user`, `system`, `kernel`
+**[1] `cpu.mode`:** Following states SHOULD be used: `user`, `system`, `kernel`
**[2]:** Required if mode is available, i.e. metrics coming from the Docker Stats API.
@@ -76,7 +76,7 @@ This metric is [opt-in][MetricOptIn].
|---|---|---|---|---|---|
| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A container's CPU metric SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` | `Conditionally Required` [2] |  |
-**[1]:** Following states SHOULD be used: `user`, `system`, `kernel`
+**[1] `cpu.mode`:** Following states SHOULD be used: `user`, `system`, `kernel`
**[2]:** Required if mode is available, i.e. metrics coming from the Docker Stats API.
diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md
index 3198bef947..6767584e55 100644
--- a/docs/system/process-metrics.md
+++ b/docs/system/process-metrics.md
@@ -65,7 +65,7 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | A process SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` | `Recommended` |  |
-**[1]:** Following states SHOULD be used: `user`, `system`, `wait`
+**[1] `cpu.mode`:** Following states SHOULD be used: `user`, `system`, `wait`
`cpu.mode` 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.
@@ -104,7 +104,7 @@ This metric is [opt-in][MetricOptIn].
|---|---|---|---|---|---|
| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | A process SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` | `Recommended` |  |
-**[1]:** Following states SHOULD be used: `user`, `system`, `wait`
+**[1] `cpu.mode`:** Following states SHOULD be used: `user`, `system`, `wait`
`cpu.mode` 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/docs/system/system-metrics.md b/docs/system/system-metrics.md
index b3f432abae..0ec0a5894c 100644
--- a/docs/system/system-metrics.md
+++ b/docs/system/system-metrics.md
@@ -124,7 +124,7 @@ This metric is [recommended][MetricRecommended].
| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A system's CPU SHOULD be characterized *either* by data points with no `mode` labels, *or only* data points with `mode` labels. [1] | `user`; `system` | `Recommended` |  |
| [`system.cpu.logical_number`](/docs/attributes-registry/system.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` |  |
-**[1]:** Following states SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`
+**[1] `cpu.mode`:** Following states SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`
`cpu.mode` 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.
@@ -164,7 +164,7 @@ This metric is [opt-in][MetricOptIn].
| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A system's CPU SHOULD be characterized *either* by data points with no `mode` labels, *or only* data points with `mode` labels. [1] | `user`; `system` | `Recommended` |  |
| [`system.cpu.logical_number`](/docs/attributes-registry/system.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` |  |
-**[1]:** Following modes SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`
+**[1] `cpu.mode`:** Following modes SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`
`cpu.mode` 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.
@@ -1001,7 +1001,7 @@ This metric is [recommended][MetricRecommended].
| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | `Recommended` |  |
| [`system.network.state`](/docs/attributes-registry/system.md) | string | A stateless protocol MUST NOT set this attribute | `close_wait` | `Recommended` |  |
-**[1]:** The value SHOULD be normalized to lowercase.
+**[1] `network.transport`:** The value SHOULD be normalized to lowercase.
Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport. For example
diff --git a/docs/url/url.md b/docs/url/url.md
index af52260559..4a21d5d289 100644
--- a/docs/url/url.md
+++ b/docs/url/url.md
@@ -37,7 +37,7 @@ This document defines semantic conventions that describe URL and its components.
| [`url.query`](/docs/attributes-registry/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [3] | `q=OpenTelemetry` | `Recommended` |  |
| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | `Recommended` |  |
-**[1]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment
+**[1] `url.full`:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment
is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless.
`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`.
@@ -61,9 +61,9 @@ This list is subject to change over time.
When a query string value is redacted, the query string key SHOULD still be preserved, e.g.
`https://www.example.com/path?color=blue&sig=REDACTED`.
-**[2]:** Sensitive content provided in `url.path` SHOULD be scrubbed when instrumentations can identify it.
+**[2] `url.path`:** Sensitive content provided in `url.path` SHOULD be scrubbed when instrumentations can identify it.
-**[3]:** Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it.
+**[3] `url.query`:** Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it.
Query string values for the following keys SHOULD be redacted by default and replaced by the value `REDACTED`:
diff --git a/templates/registry/markdown/attribute_namespace.md.j2 b/templates/registry/markdown/attribute_namespace.md.j2
index ed8fc1c654..b6329c2ba7 100644
--- a/templates/registry/markdown/attribute_namespace.md.j2
+++ b/templates/registry/markdown/attribute_namespace.md.j2
@@ -45,7 +45,7 @@
| Attribute | Type | Description | Examples | Stability |
|---|---|---|---|---|
{%- for attribute in group.attributes | sort(attribute="name") %}{% set attr_anchor = attribute.name | kebab_case %}
-| {{ attrs.name(attribute) }} | {{ attrs.type(attribute) }} | {{ attribute.brief | trim }}{{ notes.add(attribute.note) }} | {{ examples.format(attribute) | trim }} | {{ stability.badge(attribute.stability, attribute.deprecated) | trim }} |
+| {{ attrs.name(attribute) }} | {{ attrs.type(attribute) }} | {{ attribute.brief | trim }}{{ notes.add({"note": attribute.note, "name": attribute.name}) }} | {{ examples.format(attribute) | trim }} | {{ stability.badge(attribute.stability, attribute.deprecated) | trim }} |
{%- endfor %}
{{ notes.render() }}
{%- for enum in group.attributes | sort(attribute="name") %}
diff --git a/templates/registry/markdown/attribute_table.j2 b/templates/registry/markdown/attribute_table.j2
index 795512fdf2..e8756b9fbd 100644
--- a/templates/registry/markdown/attribute_table.j2
+++ b/templates/registry/markdown/attribute_table.j2
@@ -8,6 +8,6 @@
{#- Macro for creating attribute table -#}
{% macro generate(attributes, tag_filter, attribute_registry_base_url, lineage_attributes) %}{% if (tag_filter | length == 0) %}{% set filtered_attributes = attributes %}{% else %}{% set filtered_attributes = attributes | selectattr("tag", "in", tag_filter) %}{% endif %}{% if filtered_attributes | length > 0 %}| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-{% for attribute in filtered_attributes | attribute_sort %}| {{ attrs.name_with_link(attribute, attribute_registry_base_url, lineage_attributes) }} | {{ attrs.type(attribute) }} | {{ attribute.brief | trim }}{{ notes.add(attribute.note) }} | {{ examples.format(attribute) | trim }} | {{ requirement.render(attribute.requirement_level, notes) | trim }} | {{ stability.badge(attribute.stability, attribute.deprecated) | trim }} |
+{% for attribute in filtered_attributes | attribute_sort %}| {{ attrs.name_with_link(attribute, attribute_registry_base_url, lineage_attributes) }} | {{ attrs.type(attribute) }} | {{ attribute.brief | trim }}{{ notes.add({"note": attribute.note, "name": attribute.name}) }} | {{ examples.format(attribute) | trim }} | {{ requirement.render(attribute.requirement_level, notes) | trim }} | {{ stability.badge(attribute.stability, attribute.deprecated) | trim }} |
{% endfor %}{{ notes.render() }}{{ sampling.snippet(filtered_attributes, attribute_registry_base_url, lineage_attributes) }}{{ enums.tables(filtered_attributes | selectattr("type", "mapping"), notes) }}
{% endif %}{% endmacro %}
diff --git a/templates/registry/markdown/body_field_table.j2 b/templates/registry/markdown/body_field_table.j2
index af1ec232c5..a941c74afa 100644
--- a/templates/registry/markdown/body_field_table.j2
+++ b/templates/registry/markdown/body_field_table.j2
@@ -10,6 +10,6 @@
{#- Macro for creating body table -#}
{% macro generate(fields) %}{% if (fields | length > 0) %}{% set ns = namespace(flat=[])%}{% set _ = flatten(fields, ns, 0) %}| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-{% for f in ns.flat %}| {{ field_name(f.field, f.depth) }} | {{ f.field.type }} | {{ f.field.brief | trim }}{{ notes.add(f.field.note) }} | {{ examples.format(f.field) | trim }} | {{ requirement.render(f.field.requirement_level, notes) | trim }} | {{ stability.badge(f.field.stability, f.field.deprecated) | trim }} |
+{% for f in ns.flat %}| {{ field_name(f.field, f.depth) }} | {{ f.field.type }} | {{ f.field.brief | trim }}{{ notes.add({"note": f.field.note}) }} | {{ examples.format(f.field) | trim }} | {{ requirement.render(f.field.requirement_level, notes) | trim }} | {{ stability.badge(f.field.stability, f.field.deprecated) | trim }} |
{% endfor %}{{ notes.render() }}{{ enums.field_tables(ns.flat | map(attribute="field") | selectattr("type", "eq", "enum"), notes) -}}
{%- endif %}{% endmacro %}
diff --git a/templates/registry/markdown/enum_macros.j2 b/templates/registry/markdown/enum_macros.j2
index 6ad5288a78..45f67e0a5e 100644
--- a/templates/registry/markdown/enum_macros.j2
+++ b/templates/registry/markdown/enum_macros.j2
@@ -7,7 +7,7 @@
|---|---|---|
{% for espec in enum.type.members | sort(attribute='value') %}
{%- if filter(espec) == "True" -%}
-| `{{ espec.value }}` | {{ (espec.brief or espec.id) | trim }}{{ notes.add(espec.note) }} | {{ stability.badge(espec.stability, espec.deprecated) }} |
+| `{{ espec.value }}` | {{ (espec.brief or espec.id) | trim }}{{ notes.add({"note": espec.note}) }} | {{ stability.badge(espec.stability, espec.deprecated) }} |
{% endif %}{% endfor %}{{ notes.render() }}{% endmacro %}
{% macro tables(enums, notes) -%}
{% for enum in enums | sort(attribute="name") -%}
@@ -20,7 +20,7 @@
|---|---|---|
{% for espec in enum.members | sort(attribute='value') %}
{%- if filter(espec) == "True" -%}
-| `{{ espec.value }}` | {{ (espec.brief or espec.id) | trim }}{{ notes.add(espec.note) }} | {{ stability.badge(espec.stability, espec.deprecated) }} |
+| `{{ espec.value }}` | {{ (espec.brief or espec.id) | trim }}{{ notes.add({"note": espec.note}) }} | {{ stability.badge(espec.stability, espec.deprecated) }} |
{% endif %}{% endfor %}{{ notes.render() }}{% endmacro %}
{% macro field_tables(enums, notes) -%}
{% for enum in enums | sort(attribute="id") -%}
diff --git a/templates/registry/markdown/metric_table.j2 b/templates/registry/markdown/metric_table.j2
index 0d5e7a5714..ddbd191c6d 100644
--- a/templates/registry/markdown/metric_table.j2
+++ b/templates/registry/markdown/metric_table.j2
@@ -3,5 +3,5 @@
{% import 'metric_macros.j2' as metrics %}
{% macro generate(group) %}| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `{{ group.metric_name }}` | {{ metrics.instrument(group.instrument) | trim }} | `{{ group.unit }}` | {{ group.brief | trim }}{{ notes.add(group.note) }} | {{ stability.badge(group.stability, group.deprecated) | trim }} |
+| `{{ group.metric_name }}` | {{ metrics.instrument(group.instrument) | trim }} | `{{ group.unit }}` | {{ group.brief | trim }}{{ notes.add({"note": group.note}) }} | {{ stability.badge(group.stability, group.deprecated) | trim }} |
{{ notes.render() }}{% endmacro %}
diff --git a/templates/registry/markdown/notes.j2 b/templates/registry/markdown/notes.j2
index e8946078ed..a96b4270e8 100644
--- a/templates/registry/markdown/notes.j2
+++ b/templates/registry/markdown/notes.j2
@@ -1,9 +1,9 @@
{%- set ns = namespace(notes=[],index=0) -%}
-{%- macro add(note) %}{% if note %}{% set ns.notes = [ns.notes, [note]] | flatten %} [{{ ns.notes | length + ns.index }}]{% endif %}{% endmacro %}
-{%- macro add_with_limit(note) %}{% if note | length > 50 %}{% set ns.notes = [ns.notes, [note]] | flatten %} [{{ ns.notes | length + ns.index }}]{% elif note %} {{ note | trim }}{% endif %}{% endmacro %}
+{%- macro add(note) %}{% if note.note %}{% set ns.notes = [ns.notes, [note]] | flatten %} [{{ ns.notes | length + ns.index }}]{% endif %}{% endmacro %}
+{%- macro add_with_limit(note) %}{% if note.note | length > 50 %}{% set ns.notes = [ns.notes, [note]] | flatten %} [{{ ns.notes | length + ns.index }}]{% elif note.note %} {{ note.note | trim }}{% endif %}{% endmacro %}
{% macro render() %}{% if ns.notes | length > 0 %}
{%- for note in ns.notes %}
-**[{{ns.index+loop.index}}]:** {{ note | trim }}
+{% if note.name %}**[{{ns.index+loop.index}}] `{{note.name}}`:** {{ note.note | trim }}{% else -%}**[{{ns.index+loop.index}}]:** {{ note.note | trim }} {%- endif -%}
{%- if not loop.last -%}{{"\n"}}{%- endif -%}
{% endfor %}{% set ns.index = ns.notes | length + ns.index %}{% set ns.notes = [] %}
{% endif %}{% endmacro %}
diff --git a/templates/registry/markdown/requirement.j2 b/templates/registry/markdown/requirement.j2
index e35ad57d70..584c78cf2d 100644
--- a/templates/registry/markdown/requirement.j2
+++ b/templates/registry/markdown/requirement.j2
@@ -2,8 +2,8 @@
{%- if level == "recommended" %}`Recommended`
{% elif level == "required" %}`Required`
{% elif level == "opt_in" %}`Opt-In`
-{% elif level.conditionally_required %}`Conditionally Required`{{ notes.add_with_limit(level.conditionally_required) }}
-{% elif level.recommended %}`Recommended`{{ notes.add_with_limit(level.recommended) }}
+{% elif level.conditionally_required %}`Conditionally Required`{{ notes.add_with_limit({"note": level.conditionally_required}) }}
+{% elif level.recommended %}`Recommended`{{ notes.add_with_limit({"note": level.recommended}) }}
{% else %}{{ level }}
{%- endif %}
{% endmacro %}
From 4717a9fb437ba1979b7cb0c6848f46fa1553922b Mon Sep 17 00:00:00 2001
From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Date: Mon, 18 Nov 2024 18:03:29 +0100
Subject: [PATCH 02/32] [chore] Generate attr name on requirement level notes
(#1589)
---
docs/azure/events.md | 2 +-
docs/database/cassandra.md | 12 +++++------
docs/database/cosmosdb.md | 16 +++++++--------
docs/database/couchdb.md | 4 ++--
docs/database/database-metrics.md | 20 +++++++++----------
docs/database/database-spans.md | 12 +++++------
docs/database/elasticsearch.md | 4 ++--
docs/database/hbase.md | 2 +-
docs/database/mariadb.md | 10 +++++-----
docs/database/mongodb.md | 4 ++--
docs/database/mssql.md | 10 +++++-----
docs/database/mysql.md | 10 +++++-----
docs/database/postgresql.md | 10 +++++-----
docs/database/redis.md | 8 ++++----
docs/database/sql.md | 10 +++++-----
docs/dotnet/dotnet-aspnetcore-metrics.md | 12 +++++------
docs/exceptions/exceptions-logs.md | 4 ++--
docs/exceptions/exceptions-spans.md | 4 ++--
docs/faas/faas-spans.md | 2 +-
docs/feature-flags/feature-flags-logs.md | 8 ++++----
docs/gen-ai/openai.md | 4 ++--
docs/http/http-metrics.md | 12 +++++------
docs/http/http-spans.md | 8 ++++----
docs/messaging/azure-messaging.md | 10 +++++-----
docs/messaging/gcp-pubsub.md | 4 ++--
docs/messaging/kafka.md | 6 +++---
docs/messaging/messaging-metrics.md | 8 ++++----
docs/messaging/messaging-spans.md | 10 +++++-----
docs/messaging/rabbitmq.md | 2 +-
docs/messaging/rocketmq.md | 8 ++++----
docs/resource/process.md | 10 +++++-----
docs/rpc/connect-rpc.md | 2 +-
docs/rpc/rpc-spans.md | 4 ++--
docs/system/container-metrics.md | 4 ++--
.../registry/markdown/attribute_table.j2 | 2 +-
.../registry/markdown/body_field_table.j2 | 2 +-
templates/registry/markdown/requirement.j2 | 12 +++++------
37 files changed, 136 insertions(+), 136 deletions(-)
diff --git a/docs/azure/events.md b/docs/azure/events.md
index 43cc4c8998..dcf10fc02d 100644
--- a/docs/azure/events.md
+++ b/docs/azure/events.md
@@ -46,7 +46,7 @@ Describes Azure Resource Log event, see [Azure Resource Log Top-level Schema](ht
> [!Warning]
> This field contains sensitive (PII) information.
-**[2]:** if the event is tied to an Active Directory tenant.
+**[2] `tenant.id`:** if the event is tied to an Active Directory tenant.
diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md
index 7d93e91b1a..d178b576d7 100644
--- a/docs/database/cassandra.md
+++ b/docs/database/cassandra.md
@@ -58,7 +58,7 @@ SHOULD NOT be captured.
This attribute has stability level RELEASE CANDIDATE.
-**[2]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
+**[2] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
**[3] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system.
@@ -80,13 +80,13 @@ system specific term if more applicable.
This attribute has stability level RELEASE CANDIDATE.
-**[5]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
+**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
**[6] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
-**[7]:** If the operation failed and status code is available.
+**[7] `db.response.status_code`:** If the operation failed and status code is available.
**[8] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
@@ -94,7 +94,7 @@ Instrumentations SHOULD document how `error.type` is populated.
**[9] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[10]:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[10] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[11] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
@@ -103,14 +103,14 @@ This attribute has stability level RELEASE CANDIDATE.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
-**[13]:** if readily available or if instrumentation supports query summarization.
+**[13] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
**[14] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
-**[15]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[15] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
**[16] `network.peer.address`:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md
index 1662719b38..75667bb8f4 100644
--- a/docs/database/cosmosdb.md
+++ b/docs/database/cosmosdb.md
@@ -62,7 +62,7 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net
**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-**[2]:** if not `gateway` (the default value is assumed to be `gateway`).
+**[2] `db.cosmosdb.connection_mode`:** if not `gateway` (the default value is assumed to be `gateway`).
**[3] `db.operation.name`:** The `db.operation.name` has the following list of well-known values.
If one of them applies, then the respective value MUST be used.
@@ -188,7 +188,7 @@ If none of them applies, it's RECOMMENDED to use language-agnostic representatio
client method name in snake_case. Instrumentations SHOULD document
additional values when introducing new operations.
-**[4]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
+**[4] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
**[5] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
@@ -209,14 +209,14 @@ This attribute has stability level RELEASE CANDIDATE.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
-**[11]:** if readily available or if instrumentation supports query summarization.
+**[11] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
**[12] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
-**[13]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[13] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
**[14] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
@@ -363,13 +363,13 @@ system specific term if more applicable.
This attribute has stability level RELEASE CANDIDATE.
-**[3]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
+**[3] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
**[4] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
-**[5]:** If the operation failed and status code is available.
+**[5] `db.response.status_code`:** If the operation failed and status code is available.
**[6] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
@@ -377,7 +377,7 @@ Instrumentations SHOULD document how `error.type` is populated.
**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[8]:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[8] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[9] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
@@ -426,7 +426,7 @@ It captures the number of active instances at any given time. Best practices dic
**[1] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[2]:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[2] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[3] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md
index d103d6b147..fe57cd4479 100644
--- a/docs/database/couchdb.md
+++ b/docs/database/couchdb.md
@@ -35,7 +35,7 @@ The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and o
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
-**[3]:** If response was received and the HTTP response code is available.
+**[3] `db.response.status_code`:** If response was received and the HTTP response code is available.
**[4] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
@@ -43,7 +43,7 @@ Instrumentations SHOULD document how `error.type` is populated.
**[5] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[6]:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[6] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[7] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md
index bcddca7eb3..b2a5cab8ae 100644
--- a/docs/database/database-metrics.md
+++ b/docs/database/database-metrics.md
@@ -115,7 +115,7 @@ SHOULD NOT be captured.
This attribute has stability level RELEASE CANDIDATE.
-**[3]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
+**[3] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
**[4] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system.
@@ -137,13 +137,13 @@ system specific term if more applicable.
This attribute has stability level RELEASE CANDIDATE.
-**[6]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
+**[6] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
**[7] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
-**[8]:** If the operation failed and status code is available.
+**[8] `db.response.status_code`:** If the operation failed and status code is available.
**[9] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
@@ -151,13 +151,13 @@ Instrumentations SHOULD document how `error.type` is populated.
**[10] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[11]:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[11] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[12] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
-**[13]:** if readily available or if instrumentation supports query summarization.
+**[13] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
**[14] `network.peer.address`:** Semantic conventions for individual database systems SHOULD document whether `network.peer.*` attributes are applicable. Network peer address and port are useful when the application interacts with individual database nodes directly.
If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
@@ -300,7 +300,7 @@ SHOULD NOT be captured.
This attribute has stability level RELEASE CANDIDATE.
-**[3]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
+**[3] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
**[4] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system.
@@ -322,13 +322,13 @@ system specific term if more applicable.
This attribute has stability level RELEASE CANDIDATE.
-**[6]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
+**[6] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
**[7] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
-**[8]:** If the operation failed and status code is available.
+**[8] `db.response.status_code`:** If the operation failed and status code is available.
**[9] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
@@ -336,13 +336,13 @@ Instrumentations SHOULD document how `error.type` is populated.
**[10] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[11]:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[11] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[12] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
-**[13]:** if readily available or if instrumentation supports query summarization.
+**[13] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
**[14] `network.peer.address`:** Semantic conventions for individual database systems SHOULD document whether `network.peer.*` attributes are applicable. Network peer address and port are useful when the application interacts with individual database nodes directly.
If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md
index b7bda1fe06..9792853b28 100644
--- a/docs/database/database-spans.md
+++ b/docs/database/database-spans.md
@@ -133,7 +133,7 @@ SHOULD NOT be captured.
This attribute has stability level RELEASE CANDIDATE.
-**[3]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
+**[3] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
**[4] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system.
@@ -155,13 +155,13 @@ system specific term if more applicable.
This attribute has stability level RELEASE CANDIDATE.
-**[6]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
+**[6] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
**[7] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
-**[8]:** If the operation failed and status code is available.
+**[8] `db.response.status_code`:** If the operation failed and status code is available.
**[9] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
@@ -169,7 +169,7 @@ Instrumentations SHOULD document how `error.type` is populated.
**[10] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[11]:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[11] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[12] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
@@ -178,14 +178,14 @@ This attribute has stability level RELEASE CANDIDATE.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
-**[14]:** if readily available or if instrumentation supports query summarization.
+**[14] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
**[15] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
-**[16]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[16] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
**[17] `network.peer.address`:** Semantic conventions for individual database systems SHOULD document whether `network.peer.*` attributes are applicable. Network peer address and port are useful when the application interacts with individual database nodes directly.
diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md
index 8e8838a3cf..6ba8bf57fb 100644
--- a/docs/database/elasticsearch.md
+++ b/docs/database/elasticsearch.md
@@ -92,7 +92,7 @@ Instrumentations SHOULD document how `error.type` is populated.
**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[8]:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[8] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[9] `db.collection.name`:** The query may target multiple indices or data streams, in which case it SHOULD be a comma separated list of those. If the query doesn't target a specific index, this field MUST NOT be set.
@@ -108,7 +108,7 @@ For batch operations, if the individual operations are known to have the same qu
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
-**[14]:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information.
+**[14] `db.query.text`:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information.
**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
diff --git a/docs/database/hbase.md b/docs/database/hbase.md
index 7150655a03..a7a94ece17 100644
--- a/docs/database/hbase.md
+++ b/docs/database/hbase.md
@@ -62,7 +62,7 @@ Instrumentations SHOULD document how `error.type` is populated.
**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[7]:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[7] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[8] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md
index d313f41cfb..8cb960584c 100644
--- a/docs/database/mariadb.md
+++ b/docs/database/mariadb.md
@@ -50,7 +50,7 @@ SHOULD NOT be captured.
This attribute has stability level RELEASE CANDIDATE.
-**[2]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
+**[2] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
**[3] `db.namespace`:** A connection's currently associated database may change during its lifetime, e.g. from executing `USE `.
@@ -65,7 +65,7 @@ It is RECOMMENDED to capture the value as provided by the application without at
**[4] `db.operation.name`:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed.
-**[5]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
+**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
**[6] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
return code which is adopted by some database systems like PostgreSQL.
@@ -109,7 +109,7 @@ Instrumentations SHOULD document how `error.type` is populated.
**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[9]:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[9] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
@@ -118,14 +118,14 @@ This attribute has stability level RELEASE CANDIDATE.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
-**[12]:** if readily available or if instrumentation supports query summarization.
+**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
-**[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md
index 2d8d48fea5..6f0bbb54d8 100644
--- a/docs/database/mongodb.md
+++ b/docs/database/mongodb.md
@@ -52,7 +52,7 @@ This attribute has stability level RELEASE CANDIDATE.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
-**[4]:** If the operation failed and error code is available.
+**[4] `db.response.status_code`:** If the operation failed and error code is available.
**[5] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
@@ -60,7 +60,7 @@ Instrumentations SHOULD document how `error.type` is populated.
**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[7]:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[7] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[8] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
diff --git a/docs/database/mssql.md b/docs/database/mssql.md
index 475c8ff80e..078d7bd848 100644
--- a/docs/database/mssql.md
+++ b/docs/database/mssql.md
@@ -50,7 +50,7 @@ SHOULD NOT be captured.
This attribute has stability level RELEASE CANDIDATE.
-**[2]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
+**[2] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
**[3] `db.namespace`:** When connected to a default instance, `db.namespace` SHOULD be set to the name of
the database. When connected to a [named instance](https://learn.microsoft.com/sql/connect/jdbc/building-the-connection-url#named-and-multiple-sql-server-instances),
@@ -69,7 +69,7 @@ It is RECOMMENDED to capture the value as provided by the application without at
**[4] `db.operation.name`:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed.
-**[5]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
+**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
**[6] `db.response.status_code`:** Microsoft SQL Server does not report SQLSTATE.
@@ -79,7 +79,7 @@ Instrumentations SHOULD document how `error.type` is populated.
**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[9]:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[9] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
@@ -88,14 +88,14 @@ This attribute has stability level RELEASE CANDIDATE.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
-**[12]:** if readily available or if instrumentation supports query summarization.
+**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
-**[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
diff --git a/docs/database/mysql.md b/docs/database/mysql.md
index 7ad61d747b..f53f35ae16 100644
--- a/docs/database/mysql.md
+++ b/docs/database/mysql.md
@@ -50,7 +50,7 @@ SHOULD NOT be captured.
This attribute has stability level RELEASE CANDIDATE.
-**[2]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
+**[2] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
**[3] `db.namespace`:** A connection's currently associated database may change during its lifetime, e.g. from executing `USE `.
@@ -65,7 +65,7 @@ It is RECOMMENDED to capture the value as provided by the application without at
**[4] `db.operation.name`:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed.
-**[5]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
+**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
**[6] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
return code which is adopted by some database systems like PostgreSQL.
@@ -109,7 +109,7 @@ Instrumentations SHOULD document how `error.type` is populated.
**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[9]:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[9] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
@@ -118,14 +118,14 @@ This attribute has stability level RELEASE CANDIDATE.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
-**[12]:** if readily available or if instrumentation supports query summarization.
+**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
-**[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md
index 9f1586f42c..cf5736fe5f 100644
--- a/docs/database/postgresql.md
+++ b/docs/database/postgresql.md
@@ -50,7 +50,7 @@ SHOULD NOT be captured.
This attribute has stability level RELEASE CANDIDATE.
-**[2]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
+**[2] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
**[3] `db.namespace`:** `db.namespace` SHOULD be set to the combination of database and schema name following the `{database}.{schema}` pattern.
@@ -72,7 +72,7 @@ It is RECOMMENDED to capture the value as provided by the application without at
**[4] `db.operation.name`:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed.
-**[5]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
+**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
**[6] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
return code which is adopted by some database systems like PostgreSQL.
@@ -116,7 +116,7 @@ Instrumentations SHOULD document how `error.type` is populated.
**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[9]:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[9] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
@@ -125,14 +125,14 @@ This attribute has stability level RELEASE CANDIDATE.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
-**[12]:** if readily available or if instrumentation supports query summarization.
+**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
-**[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
diff --git a/docs/database/redis.md b/docs/database/redis.md
index 46ff5ec2a5..599ab64c7d 100644
--- a/docs/database/redis.md
+++ b/docs/database/redis.md
@@ -62,13 +62,13 @@ system specific term if more applicable.
This attribute has stability level RELEASE CANDIDATE.
-**[3]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
+**[3] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
**[4] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
-**[5]:** If the operation failed and status code is available.
+**[5] `db.response.status_code`:** If the operation failed and status code is available.
**[6] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
@@ -76,14 +76,14 @@ Instrumentations SHOULD document how `error.type` is populated.
**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[8]:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[8] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[9] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
**[10] `db.query.text`:** For **Redis**, the value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`.
-**[11]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text.
+**[11] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text.
See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
diff --git a/docs/database/sql.md b/docs/database/sql.md
index 65ee866da4..af808272f2 100644
--- a/docs/database/sql.md
+++ b/docs/database/sql.md
@@ -74,7 +74,7 @@ SHOULD NOT be captured.
This attribute has stability level RELEASE CANDIDATE.
-**[2]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
+**[2] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
**[3] `db.namespace`:** If a database system has multiple namespace components (e.g. schema name and database name), they SHOULD be concatenated
(potentially using database system specific conventions) from most general to most
@@ -97,7 +97,7 @@ It is RECOMMENDED to capture the value as provided by the application without at
**[4] `db.operation.name`:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed.
-**[5]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
+**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
**[6] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
return code which is adopted by some database systems like PostgreSQL.
@@ -141,7 +141,7 @@ Instrumentations SHOULD document how `error.type` is populated.
**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[9]:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[9] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
@@ -150,14 +150,14 @@ This attribute has stability level RELEASE CANDIDATE.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
-**[12]:** if readily available or if instrumentation supports query summarization.
+**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
-**[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md
index aa2daa4aaa..10213cb41c 100644
--- a/docs/dotnet/dotnet-aspnetcore-metrics.md
+++ b/docs/dotnet/dotnet-aspnetcore-metrics.md
@@ -111,7 +111,7 @@ it's RECOMMENDED to:
- Use a domain-specific attribute
- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
-**[2]:** if and only if the exception was handled by this handler.
+**[2] `aspnetcore.diagnostics.handler.type`:** if and only if the exception was handled by this handler.
`aspnetcore.diagnostics.exception.result` 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.
@@ -156,7 +156,7 @@ All rate-limiting metrics are reported by the `Microsoft.AspNetCore.RateLimiting
|---|---|---|---|---|---|
| [`aspnetcore.rate_limiting.policy`](/docs/attributes-registry/aspnetcore.md) | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | `Conditionally Required` [1] |  |
-**[1]:** if the matched endpoint for the request had a rate-limiting policy.
+**[1] `aspnetcore.rate_limiting.policy`:** if the matched endpoint for the request had a rate-limiting policy.
@@ -186,7 +186,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
|---|---|---|---|---|---|
| [`aspnetcore.rate_limiting.policy`](/docs/attributes-registry/aspnetcore.md) | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | `Conditionally Required` [1] |  |
-**[1]:** if the matched endpoint for the request had a rate-limiting policy.
+**[1] `aspnetcore.rate_limiting.policy`:** if the matched endpoint for the request had a rate-limiting policy.
@@ -212,7 +212,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
|---|---|---|---|---|---|
| [`aspnetcore.rate_limiting.policy`](/docs/attributes-registry/aspnetcore.md) | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | `Conditionally Required` [1] |  |
-**[1]:** if the matched endpoint for the request had a rate-limiting policy.
+**[1] `aspnetcore.rate_limiting.policy`:** if the matched endpoint for the request had a rate-limiting policy.
@@ -243,7 +243,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
| [`aspnetcore.rate_limiting.result`](/docs/attributes-registry/aspnetcore.md) | string | Rate-limiting result, shows whether the lease was acquired or contains a rejection reason | `acquired`; `request_canceled` | `Required` |  |
| [`aspnetcore.rate_limiting.policy`](/docs/attributes-registry/aspnetcore.md) | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | `Conditionally Required` [1] |  |
-**[1]:** if the matched endpoint for the request had a rate-limiting policy.
+**[1] `aspnetcore.rate_limiting.policy`:** if the matched endpoint for the request had a rate-limiting policy.
`aspnetcore.rate_limiting.result` 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.
@@ -284,7 +284,7 @@ Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0
| [`aspnetcore.rate_limiting.result`](/docs/attributes-registry/aspnetcore.md) | string | Rate-limiting result, shows whether the lease was acquired or contains a rejection reason | `acquired`; `request_canceled` | `Required` |  |
| [`aspnetcore.rate_limiting.policy`](/docs/attributes-registry/aspnetcore.md) | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | `Conditionally Required` [1] |  |
-**[1]:** if the matched endpoint for the request had a rate-limiting policy.
+**[1] `aspnetcore.rate_limiting.policy`:** if the matched endpoint for the request had a rate-limiting policy.
`aspnetcore.rate_limiting.result` 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/docs/exceptions/exceptions-logs.md b/docs/exceptions/exceptions-logs.md
index 58b83c7ade..c799931ae2 100644
--- a/docs/exceptions/exceptions-logs.md
+++ b/docs/exceptions/exceptions-logs.md
@@ -48,9 +48,9 @@ The table below indicates which attributes should be added to the
| [`exception.type`](/docs/attributes-registry/exception.md) | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | `Conditionally Required` [2] |  |
| [`exception.stacktrace`](/docs/attributes-registry/exception.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Recommended` |  |
-**[1]:** Required if `exception.type` is not set, recommended otherwise.
+**[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise.
-**[2]:** Required if `exception.message` is not set, recommended otherwise.
+**[2] `exception.type`:** Required if `exception.message` is not set, recommended otherwise.
diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md
index ea634f37d6..ab2cef6f29 100644
--- a/docs/exceptions/exceptions-spans.md
+++ b/docs/exceptions/exceptions-spans.md
@@ -60,9 +60,9 @@ This event describes a single exception.
| [`exception.escaped`](/docs/attributes-registry/exception.md) | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [3] | | `Recommended` |  |
| [`exception.stacktrace`](/docs/attributes-registry/exception.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Recommended` |  |
-**[1]:** Required if `exception.type` is not set, recommended otherwise.
+**[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise.
-**[2]:** Required if `exception.message` is not set, recommended otherwise.
+**[2] `exception.type`:** Required if `exception.message` is not set, recommended otherwise.
**[3] `exception.escaped`:** An exception is considered to have escaped (or left) the scope of a span,
if that span is ended while the exception is still logically "in flight".
diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md
index 3428f037f6..c5d4f9c53b 100644
--- a/docs/faas/faas-spans.md
+++ b/docs/faas/faas-spans.md
@@ -207,7 +207,7 @@ which the invoked FaaS instance reports about itself, if it's instrumented.
**[3] `faas.invoked_region`:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function.
-**[4]:** For some cloud providers, like AWS or GCP, the region in which a function is hosted is essential to uniquely identify the function and also part of its endpoint. Since it's part of the endpoint being called, the region is always known to clients. In these cases, `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional.
+**[4] `faas.invoked_region`:** For some cloud providers, like AWS or GCP, the region in which a function is hosted is essential to uniquely identify the function and also part of its endpoint. Since it's part of the endpoint being called, the region is always known to clients. In these cases, `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional.
`faas.invoked_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/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md
index 063d256c37..fbeae201fd 100644
--- a/docs/feature-flags/feature-flags-logs.md
+++ b/docs/feature-flags/feature-flags-logs.md
@@ -81,16 +81,16 @@ A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag valu
| `type_mismatch` | The type of the flag value does not match the expected type. |  |
| `general` | The error was for a reason not enumerated above. |  |
-**[2]:** If and only if an error occurred during flag evaluation.
+**[2] `error.type`:** If and only if an error occurred during flag evaluation.
**[3] `feature_flag.variant`:** A semantic identifier, commonly referred to as a variant, provides a means
for referring to a value without including the value itself. This can
provide additional context for understanding the meaning behind a value.
For example, the variant `red` maybe be used for the value `#c05543`.
-**[4]:** If feature flag provider supplies a variant or equivalent concept.
+**[4] `feature_flag.variant`:** If feature flag provider supplies a variant or equivalent concept.
-**[5]:** If and only if an error occurred. It's NOT RECOMMENDED to duplicate the value of `error.type` in `feature_flag.evaluation.error.message`.
+**[5] `feature_flag.evaluation.error.message`:** If and only if an error occurred. It's NOT RECOMMENDED to duplicate the value of `error.type` in `feature_flag.evaluation.error.message`.
`error.type` 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.
@@ -118,7 +118,7 @@ For example, the variant `red` maybe be used for the value `#c05543`.
|---|---|---|---|---|---|
| `value` | undefined | The evaluated value of the feature flag. | `#ff0000`; `1`; `true` | `Conditionally Required` [1] |  |
-**[1]:** If and only if feature flag provider does not supply variant or equivalent concept. Otherwise, `value` should be treated as opt-in.
+**[1] `value`:** If and only if feature flag provider does not supply variant or equivalent concept. Otherwise, `value` should be treated as opt-in.
diff --git a/docs/gen-ai/openai.md b/docs/gen-ai/openai.md
index ce9114ecde..12287b6e9f 100644
--- a/docs/gen-ai/openai.md
+++ b/docs/gen-ai/openai.md
@@ -66,9 +66,9 @@ attributes and ones specific the OpenAI.
the canonical name of exception that occurred, or another low-cardinality error identifier.
Instrumentations SHOULD document the list of errors they report.
-**[4]:** if the request includes a service_tier and the value is not 'auto'
+**[4] `gen_ai.openai.request.service_tier`:** if the request includes a service_tier and the value is not 'auto'
-**[5]:** if the response was received and includes a service_tier
+**[5] `gen_ai.openai.response.service_tier`:** if the response was received and includes a service_tier
**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md
index eb29e75803..0a094fe0e6 100644
--- a/docs/http/http-metrics.md
+++ b/docs/http/http-metrics.md
@@ -129,7 +129,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
-**[6]:** If not `http` and `network.protocol.version` is set.
+**[6] `network.protocol.name`:** If not `http` and `network.protocol.version` is set.
**[7] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
@@ -304,7 +304,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
-**[6]:** If not `http` and `network.protocol.version` is set.
+**[6] `network.protocol.name`:** If not `http` and `network.protocol.version` is set.
**[7] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
@@ -412,7 +412,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
-**[6]:** If not `http` and `network.protocol.version` is set.
+**[6] `network.protocol.name`:** If not `http` and `network.protocol.version` is set.
**[7] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
@@ -525,7 +525,7 @@ If the request has completed successfully, instrumentations SHOULD NOT set `erro
**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
-**[6]:** If not `http` and `network.protocol.version` is set.
+**[6] `network.protocol.name`:** If not `http` and `network.protocol.version` is set.
**[7] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
@@ -624,7 +624,7 @@ If the request has completed successfully, instrumentations SHOULD NOT set `erro
**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
-**[6]:** If not `http` and `network.protocol.version` is set.
+**[6] `network.protocol.name`:** If not `http` and `network.protocol.version` is set.
**[7] `url.template`:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation.
@@ -723,7 +723,7 @@ If the request has completed successfully, instrumentations SHOULD NOT set `erro
**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
-**[6]:** If not `http` and `network.protocol.version` is set.
+**[6] `network.protocol.name`:** If not `http` and `network.protocol.version` is set.
**[7] `url.template`:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation.
diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md
index 56aadc55a8..6dbd01c9b6 100644
--- a/docs/http/http-spans.md
+++ b/docs/http/http-spans.md
@@ -223,11 +223,11 @@ additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
-**[6]:** If and only if it's different than `http.request.method`.
+**[6] `http.request.method_original`:** If and only if it's different than `http.request.method`.
**[7] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
-**[8]:** If not `http` and `network.protocol.version` is set.
+**[8] `network.protocol.name`:** If not `http` and `network.protocol.version` is set.
**[9] `http.request.resend_count`:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other).
@@ -441,14 +441,14 @@ additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
-**[5]:** If and only if it's different than `http.request.method`.
+**[5] `http.request.method_original`:** If and only if it's different than `http.request.method`.
**[6] `http.route`:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
**[7] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
-**[8]:** If not `http` and `network.protocol.version` is set.
+**[8] `network.protocol.name`:** If not `http` and `network.protocol.version` is set.
**[9] `server.port`:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md
index 2334c6a8d7..7c8a26aa92 100644
--- a/docs/messaging/azure-messaging.md
+++ b/docs/messaging/azure-messaging.md
@@ -99,16 +99,16 @@ it's RECOMMENDED to:
**[3] `messaging.batch.message_count`:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
-**[4]:** If the span describes an operation on a batch of messages.
+**[4] `messaging.batch.message_count`:** If the span describes an operation on a batch of messages.
**[5] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
-**[6]:** If span describes operation on a single message or if the value applies to all messages in the batch.
+**[6] `messaging.destination.name`:** If span describes operation on a single message or if the value applies to all messages in the batch.
**[7] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality.
-**[8]:** If delivery count is available and is bigger than 0.
+**[8] `messaging.servicebus.message.delivery_count`:** If delivery count is available and is bigger than 0.
**[9] `server.address`:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
@@ -216,12 +216,12 @@ it's RECOMMENDED to:
**[3] `messaging.batch.message_count`:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
-**[4]:** If the span describes an operation on a batch of messages.
+**[4] `messaging.batch.message_count`:** If the span describes an operation on a batch of messages.
**[5] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
-**[6]:** If span describes operation on a single message or if the value applies to all messages in the batch.
+**[6] `messaging.destination.name`:** If span describes operation on a single message or if the value applies to all messages in the batch.
**[7] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality.
diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md
index e1fb577f63..2e490d9cfa 100644
--- a/docs/messaging/gcp-pubsub.md
+++ b/docs/messaging/gcp-pubsub.md
@@ -96,12 +96,12 @@ it's RECOMMENDED to:
**[3] `messaging.batch.message_count`:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
-**[4]:** If the span describes an operation on a batch of messages.
+**[4] `messaging.batch.message_count`:** If the span describes an operation on a batch of messages.
**[5] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
-**[6]:** If span describes operation on a single message or if the value applies to all messages in the batch.
+**[6] `messaging.destination.name`:** If span describes operation on a single message or if the value applies to all messages in the batch.
**[7] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality.
diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md
index 730ef38ad8..7164141dfe 100644
--- a/docs/messaging/kafka.md
+++ b/docs/messaging/kafka.md
@@ -97,14 +97,14 @@ it's RECOMMENDED to:
**[2] `messaging.batch.message_count`:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
-**[3]:** If the span describes an operation on a batch of messages.
+**[3] `messaging.batch.message_count`:** If the span describes an operation on a batch of messages.
**[4] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
-**[5]:** If span describes operation on a single message or if the value applies to all messages in the batch.
+**[5] `messaging.destination.name`:** If span describes operation on a single message or if the value applies to all messages in the batch.
-**[6]:** If value is `true`. When missing, the value is assumed to be `false`.
+**[6] `messaging.kafka.message.tombstone`:** If value is `true`. When missing, the value is assumed to be `false`.
**[7] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality.
diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md
index 82f492b809..72f1cf2eb1 100644
--- a/docs/messaging/messaging-metrics.md
+++ b/docs/messaging/messaging-metrics.md
@@ -110,7 +110,7 @@ it's RECOMMENDED to:
**[4] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
-**[5]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated.
+**[5] `messaging.destination.name`:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated.
**[6] `messaging.destination.subscription.name`:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.destination.subscription.name` is applicable and what it means in the context of that system.
@@ -214,7 +214,7 @@ it's RECOMMENDED to:
**[3] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
-**[4]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated.
+**[4] `messaging.destination.name`:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated.
**[5] `messaging.destination.template`:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation.
@@ -309,7 +309,7 @@ it's RECOMMENDED to:
**[4] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
-**[5]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated.
+**[5] `messaging.destination.name`:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated.
**[6] `messaging.destination.subscription.name`:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.destination.subscription.name` is applicable and what it means in the context of that system.
@@ -409,7 +409,7 @@ it's RECOMMENDED to:
**[4] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
-**[5]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated.
+**[5] `messaging.destination.name`:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated.
**[6] `messaging.destination.subscription.name`:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.destination.subscription.name` is applicable and what it means in the context of that system.
diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md
index 6ef38a52d0..2bdbcd1298 100644
--- a/docs/messaging/messaging-spans.md
+++ b/docs/messaging/messaging-spans.md
@@ -411,24 +411,24 @@ it's RECOMMENDED to:
**[3] `messaging.batch.message_count`:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
-**[4]:** If the span describes an operation on a batch of messages.
+**[4] `messaging.batch.message_count`:** If the span describes an operation on a batch of messages.
**[5] `messaging.consumer.group.name`:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.consumer.group.name` is applicable and what it means in the context of that system.
-**[6]:** If value is `true`. When missing, the value is assumed to be `false`.
+**[6] `messaging.destination.anonymous`:** If value is `true`. When missing, the value is assumed to be `false`.
**[7] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
-**[8]:** If span describes operation on a single message or if the value applies to all messages in the batch.
+**[8] `messaging.destination.name`:** If span describes operation on a single message or if the value applies to all messages in the batch.
**[9] `messaging.destination.subscription.name`:** Semantic conventions for individual messaging systems SHOULD document whether `messaging.destination.subscription.name` is applicable and what it means in the context of that system.
**[10] `messaging.destination.template`:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation.
-**[11]:** If available. Instrumentations MUST NOT use `messaging.destination.name` as template unless low-cardinality of destination name is guaranteed.
+**[11] `messaging.destination.template`:** If available. Instrumentations MUST NOT use `messaging.destination.name` as template unless low-cardinality of destination name is guaranteed.
-**[12]:** If value is `true`. When missing, the value is assumed to be `false`.
+**[12] `messaging.destination.temporary`:** If value is `true`. When missing, the value is assumed to be `false`.
**[13] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality.
diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md
index c07e597d8b..440edc516b 100644
--- a/docs/messaging/rabbitmq.md
+++ b/docs/messaging/rabbitmq.md
@@ -89,7 +89,7 @@ it's RECOMMENDED to:
**[2] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
-**[3]:** If span describes operation on a single message or if the value applies to all messages in the batch.
+**[3] `messaging.destination.name`:** If span describes operation on a single message or if the value applies to all messages in the batch.
**[4] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality.
diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md
index 04dca45b2c..8eeb14def1 100644
--- a/docs/messaging/rocketmq.md
+++ b/docs/messaging/rocketmq.md
@@ -93,18 +93,18 @@ it's RECOMMENDED to:
**[2] `messaging.batch.message_count`:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.
-**[3]:** If the span describes an operation on a batch of messages.
+**[3] `messaging.batch.message_count`:** If the span describes an operation on a batch of messages.
**[4] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
-**[5]:** If span describes operation on a single message or if the value applies to all messages in the batch.
+**[5] `messaging.destination.name`:** If span describes operation on a single message or if the value applies to all messages in the batch.
**[6] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality.
-**[7]:** If the message type is delay and delivery timestamp is not specified.
+**[7] `messaging.rocketmq.message.delay_time_level`:** If the message type is delay and delivery timestamp is not specified.
-**[8]:** If the message type is delay and delay time level is not specified.
+**[8] `messaging.rocketmq.message.delivery_timestamp`:** If the message type is delay and delay time level is not specified.
**[9] `server.address`:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
diff --git a/docs/resource/process.md b/docs/resource/process.md
index 97bd2e2e64..ba90335671 100644
--- a/docs/resource/process.md
+++ b/docs/resource/process.md
@@ -46,15 +46,15 @@
| [`process.parent_pid`](/docs/attributes-registry/process.md) | int | Parent Process identifier (PPID). | `111` | `Recommended` |  |
| [`process.pid`](/docs/attributes-registry/process.md) | int | Process identifier (PID). | `1234` | `Recommended` |  |
-**[1]:** See [Selecting process attributes](#selecting-process-attributes) for details.
+**[1] `process.command`:** See [Selecting process attributes](#selecting-process-attributes) for details.
-**[2]:** See [Selecting process attributes](#selecting-process-attributes) for details.
+**[2] `process.command_args`:** See [Selecting process attributes](#selecting-process-attributes) for details.
-**[3]:** See [Selecting process attributes](#selecting-process-attributes) for details.
+**[3] `process.command_line`:** See [Selecting process attributes](#selecting-process-attributes) for details.
-**[4]:** See [Selecting process attributes](#selecting-process-attributes) for details.
+**[4] `process.executable.name`:** See [Selecting process attributes](#selecting-process-attributes) for details.
-**[5]:** See [Selecting process attributes](#selecting-process-attributes) for details.
+**[5] `process.executable.path`:** See [Selecting process attributes](#selecting-process-attributes) for details.
diff --git a/docs/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md
index ef1e205238..16c1f09172 100644
--- a/docs/rpc/connect-rpc.md
+++ b/docs/rpc/connect-rpc.md
@@ -29,7 +29,7 @@ Below is a table of attributes that SHOULD be included on client and server Conn
| [`rpc.connect_rpc.request.metadata.`](/docs/attributes-registry/rpc.md) | string[] | Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. [2] | `rpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]` | `Opt-In` |  |
| [`rpc.connect_rpc.response.metadata.`](/docs/attributes-registry/rpc.md) | string[] | Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. [3] | `rpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]` | `Opt-In` |  |
-**[1]:** If response is not successful and if error code available.
+**[1] `rpc.connect_rpc.error_code`:** If response is not successful and if error code available.
**[2] `rpc.connect_rpc.request.metadata`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md
index 9e14b1d8dd..7ddf82cf4e 100644
--- a/docs/rpc/rpc-spans.md
+++ b/docs/rpc/rpc-spans.md
@@ -118,7 +118,7 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service
**[2] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[3]:** if the port is supported by the network transport used for communication.
+**[3] `server.port`:** if the port is supported by the network transport used for communication.
**[4] `network.transport`:** The value SHOULD be normalized to lowercase.
@@ -191,7 +191,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
**[2] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[3]:** if the port is supported by the network transport used for communication.
+**[3] `server.port`:** if the port is supported by the network transport used for communication.
**[4] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available.
diff --git a/docs/system/container-metrics.md b/docs/system/container-metrics.md
index 3ddf5a1957..69af1b7525 100644
--- a/docs/system/container-metrics.md
+++ b/docs/system/container-metrics.md
@@ -35,7 +35,7 @@ This metric is [opt-in][MetricOptIn].
**[1] `cpu.mode`:** Following states SHOULD be used: `user`, `system`, `kernel`
-**[2]:** Required if mode is available, i.e. metrics coming from the Docker Stats API.
+**[2] `cpu.mode`:** Required if mode is available, i.e. metrics coming from the Docker Stats API.
`cpu.mode` 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.
@@ -78,7 +78,7 @@ This metric is [opt-in][MetricOptIn].
**[1] `cpu.mode`:** Following states SHOULD be used: `user`, `system`, `kernel`
-**[2]:** Required if mode is available, i.e. metrics coming from the Docker Stats API.
+**[2] `cpu.mode`:** Required if mode is available, i.e. metrics coming from the Docker Stats API.
`cpu.mode` 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/templates/registry/markdown/attribute_table.j2 b/templates/registry/markdown/attribute_table.j2
index e8756b9fbd..ffd7ca6b10 100644
--- a/templates/registry/markdown/attribute_table.j2
+++ b/templates/registry/markdown/attribute_table.j2
@@ -8,6 +8,6 @@
{#- Macro for creating attribute table -#}
{% macro generate(attributes, tag_filter, attribute_registry_base_url, lineage_attributes) %}{% if (tag_filter | length == 0) %}{% set filtered_attributes = attributes %}{% else %}{% set filtered_attributes = attributes | selectattr("tag", "in", tag_filter) %}{% endif %}{% if filtered_attributes | length > 0 %}| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-{% for attribute in filtered_attributes | attribute_sort %}| {{ attrs.name_with_link(attribute, attribute_registry_base_url, lineage_attributes) }} | {{ attrs.type(attribute) }} | {{ attribute.brief | trim }}{{ notes.add({"note": attribute.note, "name": attribute.name}) }} | {{ examples.format(attribute) | trim }} | {{ requirement.render(attribute.requirement_level, notes) | trim }} | {{ stability.badge(attribute.stability, attribute.deprecated) | trim }} |
+{% for attribute in filtered_attributes | attribute_sort %}| {{ attrs.name_with_link(attribute, attribute_registry_base_url, lineage_attributes) }} | {{ attrs.type(attribute) }} | {{ attribute.brief | trim }}{{ notes.add({"note": attribute.note, "name": attribute.name}) }} | {{ examples.format(attribute) | trim }} | {{ requirement.render({"level": attribute.requirement_level, "name": attribute.name}, notes) | trim }} | {{ stability.badge(attribute.stability, attribute.deprecated) | trim }} |
{% endfor %}{{ notes.render() }}{{ sampling.snippet(filtered_attributes, attribute_registry_base_url, lineage_attributes) }}{{ enums.tables(filtered_attributes | selectattr("type", "mapping"), notes) }}
{% endif %}{% endmacro %}
diff --git a/templates/registry/markdown/body_field_table.j2 b/templates/registry/markdown/body_field_table.j2
index a941c74afa..ca97a077f0 100644
--- a/templates/registry/markdown/body_field_table.j2
+++ b/templates/registry/markdown/body_field_table.j2
@@ -10,6 +10,6 @@
{#- Macro for creating body table -#}
{% macro generate(fields) %}{% if (fields | length > 0) %}{% set ns = namespace(flat=[])%}{% set _ = flatten(fields, ns, 0) %}| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-{% for f in ns.flat %}| {{ field_name(f.field, f.depth) }} | {{ f.field.type }} | {{ f.field.brief | trim }}{{ notes.add({"note": f.field.note}) }} | {{ examples.format(f.field) | trim }} | {{ requirement.render(f.field.requirement_level, notes) | trim }} | {{ stability.badge(f.field.stability, f.field.deprecated) | trim }} |
+{% for f in ns.flat %}| {{ field_name(f.field, f.depth) }} | {{ f.field.type }} | {{ f.field.brief | trim }}{{ notes.add({"note": f.field.note}) }} | {{ examples.format(f.field) | trim }} | {{ requirement.render({"level": f.field.requirement_level, "name": f.field.id}, notes) | trim }} | {{ stability.badge(f.field.stability, f.field.deprecated) | trim }} |
{% endfor %}{{ notes.render() }}{{ enums.field_tables(ns.flat | map(attribute="field") | selectattr("type", "eq", "enum"), notes) -}}
{%- endif %}{% endmacro %}
diff --git a/templates/registry/markdown/requirement.j2 b/templates/registry/markdown/requirement.j2
index 584c78cf2d..1f5714de33 100644
--- a/templates/registry/markdown/requirement.j2
+++ b/templates/registry/markdown/requirement.j2
@@ -1,9 +1,9 @@
-{% macro render(level, notes) -%}
-{%- if level == "recommended" %}`Recommended`
-{% elif level == "required" %}`Required`
-{% elif level == "opt_in" %}`Opt-In`
-{% elif level.conditionally_required %}`Conditionally Required`{{ notes.add_with_limit({"note": level.conditionally_required}) }}
-{% elif level.recommended %}`Recommended`{{ notes.add_with_limit({"note": level.recommended}) }}
+{% macro render(attr, notes) -%}
+{%- if attr.level == "recommended" %}`Recommended`
+{% elif attr.level == "required" %}`Required`
+{% elif attr.level == "opt_in" %}`Opt-In`
+{% elif attr.level.conditionally_required %}`Conditionally Required`{{ notes.add_with_limit({"note": attr.level.conditionally_required, "name": attr.name}) }}
+{% elif attr.level.recommended %}`Recommended`{{ notes.add_with_limit({"note": attr.level.recommended, "name": attr.name}) }}
{% else %}{{ level }}
{%- endif %}
{% endmacro %}
From 25e0baecd6393d10c1b87a7074520985f0da2fac Mon Sep 17 00:00:00 2001
From: Guangya Liu
Date: Mon, 18 Nov 2024 09:17:12 -0800
Subject: [PATCH 03/32] Extend GenAI system to support IBM Watsonx AI and AWS
Bedrock (#1574)
Co-authored-by: Liudmila Molkova
---
.chloggen/1574.yaml | 22 ++++++++++++++++++++++
docs/attributes-registry/gen-ai.md | 2 ++
docs/gen-ai/gen-ai-events.md | 2 ++
docs/gen-ai/gen-ai-metrics.md | 10 ++++++++++
docs/gen-ai/gen-ai-spans.md | 2 ++
model/gen-ai/registry.yaml | 8 ++++++++
6 files changed, 46 insertions(+)
create mode 100644 .chloggen/1574.yaml
diff --git a/.chloggen/1574.yaml b/.chloggen/1574.yaml
new file mode 100644
index 0000000000..cc5fec2519
--- /dev/null
+++ b/.chloggen/1574.yaml
@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: gen-ai
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add 2 well-known gen-ai systems as reference values of the gen-ai system attribute including AWS Bedrock and IBM Watsonx AI
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [ 1574 ]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/docs/attributes-registry/gen-ai.md b/docs/attributes-registry/gen-ai.md
index c89c711244..8f50b867c6 100644
--- a/docs/attributes-registry/gen-ai.md
+++ b/docs/attributes-registry/gen-ai.md
@@ -57,8 +57,10 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
| Value | Description | Stability |
|---|---|---|
| `anthropic` | Anthropic |  |
+| `aws.bedrock` | AWS Bedrock |  |
| `az.ai.inference` | Azure AI Inference |  |
| `cohere` | Cohere |  |
+| `ibm.watsonx.ai` | IBM Watsonx AI |  |
| `openai` | OpenAI |  |
| `vertex_ai` | Vertex AI |  |
diff --git a/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md
index c5595966de..5870694ec7 100644
--- a/docs/gen-ai/gen-ai-events.md
+++ b/docs/gen-ai/gen-ai-events.md
@@ -80,8 +80,10 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
| Value | Description | Stability |
|---|---|---|
| `anthropic` | Anthropic |  |
+| `aws.bedrock` | AWS Bedrock |  |
| `az.ai.inference` | Azure AI Inference |  |
| `cohere` | Cohere |  |
+| `ibm.watsonx.ai` | IBM Watsonx AI |  |
| `openai` | OpenAI |  |
| `vertex_ai` | Vertex AI |  |
diff --git a/docs/gen-ai/gen-ai-metrics.md b/docs/gen-ai/gen-ai-metrics.md
index 0ab10904e1..6f5d09d9d9 100644
--- a/docs/gen-ai/gen-ai-metrics.md
+++ b/docs/gen-ai/gen-ai-metrics.md
@@ -97,8 +97,10 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
| Value | Description | Stability |
|---|---|---|
| `anthropic` | Anthropic |  |
+| `aws.bedrock` | AWS Bedrock |  |
| `az.ai.inference` | Azure AI Inference |  |
| `cohere` | Cohere |  |
+| `ibm.watsonx.ai` | IBM Watsonx AI |  |
| `openai` | OpenAI |  |
| `vertex_ai` | Vertex AI |  |
@@ -179,8 +181,10 @@ Instrumentations SHOULD document the list of errors they report.
| Value | Description | Stability |
|---|---|---|
| `anthropic` | Anthropic |  |
+| `aws.bedrock` | AWS Bedrock |  |
| `az.ai.inference` | Azure AI Inference |  |
| `cohere` | Cohere |  |
+| `ibm.watsonx.ai` | IBM Watsonx AI |  |
| `openai` | OpenAI |  |
| `vertex_ai` | Vertex AI |  |
@@ -261,8 +265,10 @@ Instrumentations SHOULD document the list of errors they report.
| Value | Description | Stability |
|---|---|---|
| `anthropic` | Anthropic |  |
+| `aws.bedrock` | AWS Bedrock |  |
| `az.ai.inference` | Azure AI Inference |  |
| `cohere` | Cohere |  |
+| `ibm.watsonx.ai` | IBM Watsonx AI |  |
| `openai` | OpenAI |  |
| `vertex_ai` | Vertex AI |  |
@@ -332,8 +338,10 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
| Value | Description | Stability |
|---|---|---|
| `anthropic` | Anthropic |  |
+| `aws.bedrock` | AWS Bedrock |  |
| `az.ai.inference` | Azure AI Inference |  |
| `cohere` | Cohere |  |
+| `ibm.watsonx.ai` | IBM Watsonx AI |  |
| `openai` | OpenAI |  |
| `vertex_ai` | Vertex AI |  |
@@ -402,8 +410,10 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
| Value | Description | Stability |
|---|---|---|
| `anthropic` | Anthropic |  |
+| `aws.bedrock` | AWS Bedrock |  |
| `az.ai.inference` | Azure AI Inference |  |
| `cohere` | Cohere |  |
+| `ibm.watsonx.ai` | IBM Watsonx AI |  |
| `openai` | OpenAI |  |
| `vertex_ai` | Vertex AI |  |
diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md
index e4bc72c0e5..a05a0993cf 100644
--- a/docs/gen-ai/gen-ai-spans.md
+++ b/docs/gen-ai/gen-ai-spans.md
@@ -104,8 +104,10 @@ Instrumentations SHOULD document the list of errors they report.
| Value | Description | Stability |
|---|---|---|
| `anthropic` | Anthropic |  |
+| `aws.bedrock` | AWS Bedrock |  |
| `az.ai.inference` | Azure AI Inference |  |
| `cohere` | Cohere |  |
+| `ibm.watsonx.ai` | IBM Watsonx AI |  |
| `openai` | OpenAI |  |
| `vertex_ai` | Vertex AI |  |
diff --git a/model/gen-ai/registry.yaml b/model/gen-ai/registry.yaml
index 2be38beb2b..ecf76ca612 100644
--- a/model/gen-ai/registry.yaml
+++ b/model/gen-ai/registry.yaml
@@ -29,6 +29,14 @@ groups:
stability: experimental
value: "az.ai.inference"
brief: 'Azure AI Inference'
+ - id: ibm.watsonx.ai
+ stability: experimental
+ value: "ibm.watsonx.ai"
+ brief: 'IBM Watsonx AI'
+ - id: aws.bedrock
+ stability: experimental
+ value: "aws.bedrock"
+ brief: 'AWS Bedrock'
brief: The Generative AI product as identified by the client or server instrumentation.
note: |
The `gen_ai.system` describes a family of GenAI models with specific model identified
From c5093dddb8bb756c0179424c9e182abfbb57636a Mon Sep 17 00:00:00 2001
From: Gergely Kalapos
Date: Tue, 19 Nov 2024 10:08:52 +0100
Subject: [PATCH 04/32] Add geo fields into attribute registry (#1116)
Co-authored-by: Liudmila Molkova
---
.chloggen/geo_fields.yaml | 17 +++++
.github/ISSUE_TEMPLATE/bug_report.yaml | 1 +
.github/ISSUE_TEMPLATE/change_proposal.yaml | 1 +
.github/ISSUE_TEMPLATE/new-conventions.yaml | 1 +
docs/attributes-registry/README.md | 1 +
docs/attributes-registry/geo.md | 34 +++++++++
model/geo/registry.yaml | 83 +++++++++++++++++++++
7 files changed, 138 insertions(+)
create mode 100755 .chloggen/geo_fields.yaml
create mode 100644 docs/attributes-registry/geo.md
create mode 100644 model/geo/registry.yaml
diff --git a/.chloggen/geo_fields.yaml b/.chloggen/geo_fields.yaml
new file mode 100755
index 0000000000..452a456333
--- /dev/null
+++ b/.chloggen/geo_fields.yaml
@@ -0,0 +1,17 @@
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: new_component
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: geo
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add geo fields to attribute registry.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1033]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
index e4e6d6b430..35d7e1ad75 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yaml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -49,6 +49,7 @@ body:
- area:file
- area:gcp
- area:gen-ai
+ - area:geo
- area:go
- area:graphql
- area:hardware
diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml
index 4c9316ddf1..7ca9195edb 100644
--- a/.github/ISSUE_TEMPLATE/change_proposal.yaml
+++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml
@@ -41,6 +41,7 @@ body:
- area:file
- area:gcp
- area:gen-ai
+ - area:geo
- area:go
- area:graphql
- area:hardware
diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml
index e6e543158e..89ab5516f4 100644
--- a/.github/ISSUE_TEMPLATE/new-conventions.yaml
+++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml
@@ -50,6 +50,7 @@ body:
- area:file
- area:gcp
- area:gen-ai
+ - area:geo
- area:go
- area:graphql
- area:hardware
diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md
index 35356a67cb..4d80dbfe2f 100644
--- a/docs/attributes-registry/README.md
+++ b/docs/attributes-registry/README.md
@@ -61,6 +61,7 @@ Currently, the following namespaces exist:
- [File](file.md)
- [GCP](gcp.md)
- [Gen AI](gen-ai.md)
+- [Geo](geo.md)
- [Go](go.md)
- [GraphQL](graphql.md)
- [Hardware](hardware.md)
diff --git a/docs/attributes-registry/geo.md b/docs/attributes-registry/geo.md
new file mode 100644
index 0000000000..64440ee478
--- /dev/null
+++ b/docs/attributes-registry/geo.md
@@ -0,0 +1,34 @@
+
+
+
+
+
+# Geo
+
+## Geo Attributes
+
+Geo fields can carry data about a specific location related to an event. This geolocation information can be derived from techniques such as Geo IP, or be user-supplied.
+Note: Geo attributes are typically used under another namespace, such as client.* and describe the location of the corresponding entity (device, end-user, etc). Semantic conventions that reference geo attributes (as a root namespace) or embed them (under their own namespace) SHOULD document what geo attributes describe in the scope of that convention.
+
+| Attribute | Type | Description | Examples | Stability |
+|---|---|---|---|---|
+| `geo.continent.code` | string | Two-letter code representing continent’s name. | `AF`; `AN`; `AS` |  |
+| `geo.country.iso_code` | string | Two-letter ISO Country Code ([ISO 3166-1 alpha2](https://en.wikipedia.org/wiki/ISO_3166-1#Codes)). | `CA` |  |
+| `geo.locality.name` | string | Locality name. Represents the name of a city, town, village, or similar populated place. | `Montreal`; `Berlin` |  |
+| `geo.location.lat` | double | Latitude of the geo location in [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84). | `45.505918` |  |
+| `geo.location.lon` | double | Longitude of the geo location in [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84). | `-73.61483` |  |
+| `geo.postal_code` | string | Postal code associated with the location. Values appropriate for this field may also be known as a postcode or ZIP code and will vary widely from country to country. | `94040` |  |
+| `geo.region.iso_code` | string | Region ISO code ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)). | `CA-QC` |  |
+
+`geo.continent.code` 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.
+
+| Value | Description | Stability |
+|---|---|---|
+| `AF` | Africa |  |
+| `AN` | Antarctica |  |
+| `AS` | Asia |  |
+| `EU` | Europe |  |
+| `NA` | North America |  |
+| `OC` | Oceania |  |
+| `SA` | South America |  |
diff --git a/model/geo/registry.yaml b/model/geo/registry.yaml
new file mode 100644
index 0000000000..41cb4afb38
--- /dev/null
+++ b/model/geo/registry.yaml
@@ -0,0 +1,83 @@
+groups:
+ - id: registry.geo
+ type: attribute_group
+ brief: >
+ Geo fields can carry data about a specific location related to an event.
+ This geolocation information can be derived from techniques such as Geo IP, or be user-supplied.
+
+ Note: Geo attributes are typically used under another namespace, such as client.* and describe the location of the corresponding
+ entity (device, end-user, etc). Semantic conventions that reference geo attributes (as a root namespace) or embed them
+ (under their own namespace) SHOULD document what geo attributes describe in the scope of that convention.
+
+ attributes:
+ - id: geo.locality.name
+ stability: experimental
+ type: string
+ brief: >
+ Locality name. Represents the name of a city, town, village, or similar populated place.
+ examples: [ 'Montreal', 'Berlin' ]
+ - id: geo.continent.code
+ stability: experimental
+ brief: >
+ Two-letter code representing continent’s name.
+ type:
+ members:
+ - id: 'af'
+ stability: experimental
+ value: 'AF'
+ brief: 'Africa'
+ - id: 'an'
+ stability: experimental
+ value: 'AN'
+ brief: 'Antarctica'
+ - id: 'as'
+ stability: experimental
+ value: 'AS'
+ brief: 'Asia'
+ - id: 'eu'
+ stability: experimental
+ value: 'EU'
+ brief: 'Europe'
+ - id: 'na'
+ stability: experimental
+ value: 'NA'
+ brief: 'North America'
+ - id: 'oc'
+ stability: experimental
+ value: 'OC'
+ brief: 'Oceania'
+ - id: 'sa'
+ stability: experimental
+ value: 'SA'
+ brief: 'South America'
+ - id: geo.country.iso_code
+ stability: experimental
+ type: string
+ brief: >
+ Two-letter ISO Country Code ([ISO 3166-1 alpha2](https://en.wikipedia.org/wiki/ISO_3166-1#Codes)).
+ examples: [ 'CA' ]
+ - id: geo.location.lon
+ stability: experimental
+ type: double
+ brief: >
+ Longitude of the geo location in [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84).
+ examples: [ -73.614830 ]
+ - id: geo.location.lat
+ stability: experimental
+ type: double
+ brief: >
+ Latitude of the geo location in [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84).
+ examples: [ 45.505918 ]
+ - id: geo.postal_code
+ stability: experimental
+ type: string
+ brief: >
+ Postal code associated with the location.
+ Values appropriate for this field may also be known as a postcode or ZIP code and will vary widely from country to country.
+ examples: [ '94040' ]
+ - id: geo.region.iso_code
+ stability: experimental
+ type: string
+ brief: >
+ Region ISO code ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)).
+ examples: [ 'CA-QC' ]
From 9a5931070bef3c5586876cf25054b6d5b8512da6 Mon Sep 17 00:00:00 2001
From: Braydon Kains <93549768+braydonk@users.noreply.github.com>
Date: Wed, 20 Nov 2024 18:37:27 -0500
Subject: [PATCH 05/32] [chore] Add lightweight make check target (#1586)
Co-authored-by: Liudmila Molkova
Co-authored-by: Trask Stalnaker
Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com>
---
Makefile | 9 +++++++--
1 file changed, 7 insertions(+), 2 deletions(-)
diff --git a/Makefile b/Makefile
index fe34a79849..6f2cf5c809 100644
--- a/Makefile
+++ b/Makefile
@@ -35,11 +35,16 @@ OPA_CONTAINER=$(shell cat dependencies.Dockerfile | awk '$$4=="opa" {print $$2}'
DOCKER_USER=$(shell id -u):$(shell id -g)
+CHECK_TARGETS=install-tools markdownlint misspell table-check compatibility-check \
+ schema-check check-file-and-folder-names-in-docs
+
# TODO: add `yamllint` step to `all` after making sure it works on Mac.
.PHONY: all
-all: install-tools markdownlint markdown-link-check misspell table-check compatibility-check schema-check \
- check-file-and-folder-names-in-docs
+all: $(CHECK_TARGETS) markdown-link-check
+
+.PHONY: check
+check: $(CHECK_TARGETS)
.PHONY: check-file-and-folder-names-in-docs
check-file-and-folder-names-in-docs:
From 2566b8bb0551dc36d6d1de59423948853301b329 Mon Sep 17 00:00:00 2001
From: Sourabh Jain
Date: Thu, 21 Nov 2024 09:19:46 +0530
Subject: [PATCH 06/32] Cosmos DB: Added regions_contacted as new dimension
(#1525)
Co-authored-by: Justine Cocchi
Co-authored-by: Liudmila Molkova
Co-authored-by: Trask Stalnaker
---
...sers_sourabhjain_moreoperationmetrics.yaml | 22 +++++++
docs/attributes-registry/db.md | 7 ++-
docs/database/cosmosdb.md | 60 ++++++++++---------
model/database/cosmosdb-metrics.yaml | 4 ++
model/database/registry.yaml | 12 +++-
model/database/spans.yaml | 3 +
6 files changed, 78 insertions(+), 30 deletions(-)
create mode 100644 .chloggen/users_sourabhjain_moreoperationmetrics.yaml
diff --git a/.chloggen/users_sourabhjain_moreoperationmetrics.yaml b/.chloggen/users_sourabhjain_moreoperationmetrics.yaml
new file mode 100644
index 0000000000..8c2dad39df
--- /dev/null
+++ b/.chloggen/users_sourabhjain_moreoperationmetrics.yaml
@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: db
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Added `db.cosmosdb.regions_contacted` attribute to Cosmos DB metrics and traces.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1525]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md
index ca43d19780..927ce0f6f2 100644
--- a/docs/attributes-registry/db.md
+++ b/docs/attributes-registry/db.md
@@ -195,10 +195,13 @@ This group defines attributes for Azure Cosmos DB.
| `db.cosmosdb.client_id` | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` |  |
| `db.cosmosdb.connection_mode` | string | Cosmos client connection mode. | `gateway`; `direct` |  |
| `db.cosmosdb.consistency_level` | string | Account or request [consistency level](https://learn.microsoft.com/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong`; `Session` |  |
+| `db.cosmosdb.regions_contacted` | string[] | List of regions contacted during operation in the order that they were contacted. If there is more than one region listed, it indicates that the operation was performed on multiple regions i.e. cross-regional call. [10] | `["North Central US", "Australia East", "Australia Southeast"]` |  |
| `db.cosmosdb.request_charge` | double | Request units consumed for the operation. | `46.18`; `1.0` |  |
| `db.cosmosdb.request_content_length` | int | Request payload size in bytes. | |  |
| `db.cosmosdb.sub_status_code` | int | Cosmos DB sub status code. | `1000`; `1002` |  |
+**[10] `db.cosmosdb.regions_contacted`:** Region name matches the format of `displayName` in [Azure Location API](https://learn.microsoft.com/rest/api/subscription/subscriptions/list-locations?view=rest-subscription-2021-10-01&tabs=HTTP#location)
+
`db.cosmosdb.connection_mode` 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.
| Value | Description | Stability |
@@ -223,9 +226,9 @@ This group defines attributes for Elasticsearch.
| Attribute | Type | Description | Examples | Stability |
|---|---|---|---|---|
| `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` |  |
-| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [10] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` |  |
+| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [11] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` |  |
-**[10] `db.elasticsearch.path_parts`:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names.
+**[11] `db.elasticsearch.path_parts`:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names.
## Deprecated Database Attributes
diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md
index 75667bb8f4..0247ef7372 100644
--- a/docs/database/cosmosdb.md
+++ b/docs/database/cosmosdb.md
@@ -42,29 +42,32 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net
| [`db.collection.name`](/docs/attributes-registry/db.md) | string | Cosmos DB container name. [1] | `public.users`; `customers` | `Conditionally Required` if available |  |
| [`db.cosmosdb.connection_mode`](/docs/attributes-registry/db.md) | string | Cosmos client connection mode. | `gateway`; `direct` | `Conditionally Required` [2] |  |
| [`db.cosmosdb.consistency_level`](/docs/attributes-registry/db.md) | string | Account or request [consistency level](https://learn.microsoft.com/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong`; `Session` | `Conditionally Required` If available. |  |
+| [`db.cosmosdb.regions_contacted`](/docs/attributes-registry/db.md) | string[] | List of regions contacted during operation in the order that they were contacted. If there is more than one region listed, it indicates that the operation was performed on multiple regions i.e. cross-regional call. [3] | `["North Central US", "Australia East", "Australia Southeast"]` | `Conditionally Required` If available. |  |
| [`db.cosmosdb.request_charge`](/docs/attributes-registry/db.md) | double | Request units consumed for the operation. | `46.18`; `1.0` | `Conditionally Required` when available |  |
| [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` when response was received and contained sub-code. |  |
| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. |  |
-| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [3] | `create_item`; `query_items`; `read_item` | `Conditionally Required` [4] |  |
+| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `create_item`; `query_items`; `read_item` | `Conditionally Required` [5] |  |
| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Cosmos DB row count in result set. | `10`; `20` | `Conditionally Required` if response was received and returned any rows |  |
-| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Cosmos DB status code. [5] | `200`; `201` | `Conditionally Required` if response was received |  |
-| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [6] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. |  |
-| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Conditionally Required` If not default (443). |  |
-| [`az.namespace`](/docs/attributes-registry/azure.md) | string | [Azure Resource Provider Namespace](https://learn.microsoft.com/azure/azure-resource-manager/management/azure-services-resource-providers) as recognized by the client. [8] | `Microsoft.DocumentDB` | `Recommended` |  |
+| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Cosmos DB status code. [6] | `200`; `201` | `Conditionally Required` if response was received |  |
+| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [7] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. |  |
+| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [8] | `80`; `8080`; `443` | `Conditionally Required` If not default (443). |  |
+| [`az.namespace`](/docs/attributes-registry/azure.md) | string | [Azure Resource Provider Namespace](https://learn.microsoft.com/azure/azure-resource-manager/management/azure-services-resource-providers) as recognized by the client. [9] | `Microsoft.DocumentDB` | `Recommended` |  |
| [`db.cosmosdb.client_id`](/docs/attributes-registry/db.md) | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | `Recommended` |  |
| [`db.cosmosdb.request_content_length`](/docs/attributes-registry/db.md) | int | Request payload size in bytes. | | `Recommended` |  |
-| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [9] | `2`; `3`; `4` | `Recommended` |  |
-| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [10] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [11] |  |
-| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [12] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [13] |  |
-| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [14] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [15] | `cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|` | `Recommended` |  |
-| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` |  |
+| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [10] | `2`; `3`; `4` | `Recommended` |  |
+| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] |  |
+| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] |  |
+| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
+| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [16] | `cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|` | `Recommended` |  |
+| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [17] | `someval`; `55` | `Opt-In` |  |
**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
**[2] `db.cosmosdb.connection_mode`:** if not `gateway` (the default value is assumed to be `gateway`).
-**[3] `db.operation.name`:** The `db.operation.name` has the following list of well-known values.
+**[3] `db.cosmosdb.regions_contacted`:** Region name matches the format of `displayName` in [Azure Location API](https://learn.microsoft.com/rest/api/subscription/subscriptions/list-locations?view=rest-subscription-2021-10-01&tabs=HTTP#location)
+
+**[4] `db.operation.name`:** The `db.operation.name` has the following list of well-known values.
If one of them applies, then the respective value MUST be used.
Batch operations:
@@ -188,44 +191,44 @@ If none of them applies, it's RECOMMENDED to use language-agnostic representatio
client method name in snake_case. Instrumentations SHOULD document
additional values when introducing new operations.
-**[4] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
+**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-**[5] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
+**[6] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
This attribute has stability level RELEASE CANDIDATE.
-**[6] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[7] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[8] `az.namespace`:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.DocumentDB` for all operations performed by Cosmos DB client.
+**[9] `az.namespace`:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.DocumentDB` for all operations performed by Cosmos DB client.
-**[9] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[10] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+**[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
This attribute has stability level RELEASE CANDIDATE.
-**[11] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
+**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
-**[12] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
-**[13] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
-**[14] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[15] `user_agent.original`:** The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled.
+**[16] `user_agent.original`:** The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled.
Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it).
Default value is "NS".
-**[16] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
+**[17] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`.
This attribute has stability level RELEASE CANDIDATE.
@@ -344,7 +347,8 @@ Explaining bucket configuration:
| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [4] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [5] |  |
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [6] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Conditionally Required` [8] |  |
-| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
+| [`db.cosmosdb.regions_contacted`](/docs/attributes-registry/db.md) | string[] | List of regions contacted during operation in the order that they were contacted. If there is more than one region listed, it indicates that the operation was performed on multiple regions i.e. cross-regional call. [9] | `["North Central US", "Australia East", "Australia Southeast"]` | `Recommended` If available |  |
+| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
@@ -379,7 +383,9 @@ Instrumentations SHOULD document how `error.type` is populated.
**[8] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[9] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[9] `db.cosmosdb.regions_contacted`:** Region name matches the format of `displayName` in [Azure Location API](https://learn.microsoft.com/rest/api/subscription/subscriptions/list-locations?view=rest-subscription-2021-10-01&tabs=HTTP#location)
+
+**[10] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
`db.cosmosdb.consistency_level` 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/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml
index 3946880699..bd2a548eed 100644
--- a/model/database/cosmosdb-metrics.yaml
+++ b/model/database/cosmosdb-metrics.yaml
@@ -7,6 +7,10 @@ groups:
unit: "{request_unit}"
stability: experimental
extends: attributes.db.cosmosdb.minimal
+ attributes:
+ - ref: db.cosmosdb.regions_contacted
+ requirement_level:
+ recommended: If available
- id: metric.db.client.cosmosdb.active_instance.count
type: metric
diff --git a/model/database/registry.yaml b/model/database/registry.yaml
index 2913ed4e64..a453421878 100644
--- a/model/database/registry.yaml
+++ b/model/database/registry.yaml
@@ -544,7 +544,17 @@ groups:
stability: experimental
brief: Account or request [consistency level](https://learn.microsoft.com/azure/cosmos-db/consistency-levels).
examples: ["Eventual", "ConsistentPrefix", "BoundedStaleness", "Strong", "Session"]
-
+ - id: db.cosmosdb.regions_contacted
+ type: string[]
+ stability: experimental
+ brief: >
+ List of regions contacted during operation in the order that they were contacted. If there is more than one region listed,
+ it indicates that the operation was performed on multiple regions i.e. cross-regional call.
+ note: >
+ Region name matches the format of `displayName`
+ in [Azure Location API](https://learn.microsoft.com/rest/api/subscription/subscriptions/list-locations?view=rest-subscription-2021-10-01&tabs=HTTP#location)
+ examples:
+ - ["North Central US", "Australia East", "Australia Southeast"]
- id: registry.db.elasticsearch
type: attribute_group
display_name: Elasticsearch Attributes
diff --git a/model/database/spans.yaml b/model/database/spans.yaml
index f4b32c0336..8a5d087d7c 100644
--- a/model/database/spans.yaml
+++ b/model/database/spans.yaml
@@ -737,3 +737,6 @@ groups:
- ref: db.cosmosdb.consistency_level
requirement_level:
conditionally_required: If available.
+ - ref: db.cosmosdb.regions_contacted
+ requirement_level:
+ conditionally_required: If available.
From 05dca2da88a4fd6708291ba2da1706a23867dd8a Mon Sep 17 00:00:00 2001
From: Daniel Dyla
Date: Wed, 20 Nov 2024 23:08:42 -0500
Subject: [PATCH 07/32] Add enum value separators (#1572)
---
.chloggen/enum-values-separators.yaml | 22 +++++++++
docs/attributes-registry/android.md | 2 +
docs/attributes-registry/aspnetcore.md | 6 +++
docs/attributes-registry/aws.md | 2 +
docs/attributes-registry/cicd.md | 2 +
docs/attributes-registry/cloud.md | 4 ++
docs/attributes-registry/container.md | 2 +
docs/attributes-registry/cpu.md | 2 +
docs/attributes-registry/db.md | 16 +++++++
docs/attributes-registry/deployment.md | 2 +
docs/attributes-registry/disk.md | 2 +
docs/attributes-registry/dotnet.md | 2 +
docs/attributes-registry/error.md | 2 +
docs/attributes-registry/faas.md | 6 +++
docs/attributes-registry/feature-flag.md | 2 +
docs/attributes-registry/gen-ai.md | 10 +++++
docs/attributes-registry/geo.md | 2 +
docs/attributes-registry/go.md | 2 +
docs/attributes-registry/graphql.md | 2 +
docs/attributes-registry/hardware.md | 4 ++
docs/attributes-registry/host.md | 2 +
docs/attributes-registry/http.md | 6 +++
docs/attributes-registry/ios.md | 2 +
docs/attributes-registry/jvm.md | 4 ++
docs/attributes-registry/k8s.md | 2 +
docs/attributes-registry/linux.md | 2 +
docs/attributes-registry/log.md | 2 +
docs/attributes-registry/messaging.md | 10 +++++
docs/attributes-registry/network.md | 14 ++++++
docs/attributes-registry/nodejs.md | 2 +
docs/attributes-registry/opentracing.md | 2 +
docs/attributes-registry/os.md | 2 +
docs/attributes-registry/otel.md | 2 +
docs/attributes-registry/process.md | 6 +++
docs/attributes-registry/profile.md | 2 +
docs/attributes-registry/rpc.md | 10 +++++
docs/attributes-registry/signalr.md | 4 ++
docs/attributes-registry/system.md | 20 +++++++++
docs/attributes-registry/telemetry.md | 2 +
docs/attributes-registry/test.md | 4 ++
docs/attributes-registry/tls.md | 2 +
docs/attributes-registry/v8js.md | 4 ++
docs/attributes-registry/vcs.md | 14 ++++++
docs/cicd/cicd-metrics.md | 20 +++++++++
docs/cloud-providers/aws-sdk.md | 2 +
docs/database/cassandra.md | 4 ++
docs/database/cosmosdb.md | 10 +++++
docs/database/couchdb.md | 2 +
docs/database/database-metrics.md | 10 +++++
docs/database/database-spans.md | 4 ++
docs/database/dynamodb.md | 26 +++++++++++
docs/database/elasticsearch.md | 4 ++
docs/database/hbase.md | 2 +
docs/database/mariadb.md | 2 +
docs/database/mongodb.md | 2 +
docs/database/mssql.md | 2 +
docs/database/mysql.md | 2 +
docs/database/postgresql.md | 2 +
docs/database/redis.md | 2 +
docs/database/sql.md | 2 +
docs/dns/dns-metrics.md | 2 +
docs/dotnet/dotnet-aspnetcore-metrics.md | 10 +++++
docs/dotnet/dotnet-kestrel-metrics.md | 36 +++++++++++++++
docs/dotnet/dotnet-signalr-metrics.md | 8 ++++
docs/faas/faas-metrics.md | 18 ++++++++
docs/faas/faas-spans.md | 8 ++++
docs/feature-flags/feature-flags-logs.md | 4 ++
docs/gen-ai/azure-ai-inference.md | 4 ++
docs/gen-ai/gen-ai-events.md | 2 +
docs/gen-ai/gen-ai-metrics.md | 26 +++++++++++
docs/gen-ai/gen-ai-spans.md | 6 +++
docs/gen-ai/openai.md | 8 ++++
docs/general/attributes.md | 8 ++++
docs/general/logs.md | 2 +
docs/general/profiles.md | 2 +
docs/general/trace-compatibility.md | 2 +
docs/graphql/graphql-spans.md | 2 +
docs/hardware/common.md | 14 ++++++
docs/http/http-metrics.md | 30 +++++++++++++
docs/http/http-spans.md | 12 +++++
docs/messaging/azure-messaging.md | 10 +++++
docs/messaging/gcp-pubsub.md | 4 ++
docs/messaging/kafka.md | 4 ++
docs/messaging/messaging-metrics.md | 18 ++++++++
docs/messaging/messaging-spans.md | 6 +++
docs/messaging/rabbitmq.md | 4 ++
docs/messaging/rocketmq.md | 8 ++++
docs/object-stores/s3.md | 2 +
docs/resource/README.md | 2 +
docs/resource/cloud-provider/aws/ecs.md | 2 +
docs/resource/cloud.md | 4 ++
docs/resource/host.md | 2 +
docs/resource/os.md | 2 +
docs/rpc/connect-rpc.md | 2 +
docs/rpc/grpc.md | 2 +
docs/rpc/rpc-metrics.md | 6 +++
docs/rpc/rpc-spans.md | 14 ++++++
docs/runtime/dotnet-metrics.md | 10 +++++
docs/runtime/go-metrics.md | 2 +
docs/runtime/jvm-metrics.md | 12 +++++
docs/runtime/nodejs-metrics.md | 2 +
docs/runtime/v8js-metrics.md | 10 +++++
docs/system/container-metrics.md | 8 ++++
docs/system/process-metrics.md | 12 +++++
docs/system/system-metrics.md | 52 ++++++++++++++++++++++
templates/registry/markdown/enum_macros.j2 | 2 +
106 files changed, 718 insertions(+)
create mode 100755 .chloggen/enum-values-separators.yaml
diff --git a/.chloggen/enum-values-separators.yaml b/.chloggen/enum-values-separators.yaml
new file mode 100755
index 0000000000..9fa166d99b
--- /dev/null
+++ b/.chloggen/enum-values-separators.yaml
@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: docs
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Improve separation between attribute table footnotes and enum values
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1569]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/docs/attributes-registry/android.md b/docs/attributes-registry/android.md
index ce172dacd5..69cfaeb065 100644
--- a/docs/attributes-registry/android.md
+++ b/docs/attributes-registry/android.md
@@ -27,6 +27,8 @@ This document defines attributes that represents an occurrence of a lifecycle tr
**[1] `android.state`:** The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived.
+---
+
`android.state` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/aspnetcore.md b/docs/attributes-registry/aspnetcore.md
index 30ef935ff6..6adeb3584d 100644
--- a/docs/attributes-registry/aspnetcore.md
+++ b/docs/attributes-registry/aspnetcore.md
@@ -20,6 +20,8 @@ ASP.NET Core attributes
| `aspnetcore.routing.is_fallback` | boolean | A value that indicates whether the matched route is a fallback route. | `true` |  |
| `aspnetcore.routing.match_status` | string | Match result - success or failure | `success`; `failure` |  |
+---
+
`aspnetcore.diagnostics.exception.result` 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.
| Value | Description | Stability |
@@ -29,6 +31,8 @@ ASP.NET Core attributes
| `skipped` | Exception handling was skipped because the response had started. |  |
| `unhandled` | Exception was not handled by the exception handling middleware. |  |
+---
+
`aspnetcore.rate_limiting.result` 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.
| Value | Description | Stability |
@@ -38,6 +42,8 @@ ASP.NET Core attributes
| `global_limiter` | Lease request was rejected by the global limiter |  |
| `request_canceled` | Lease request was canceled |  |
+---
+
`aspnetcore.routing.match_status` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/aws.md b/docs/attributes-registry/aws.md
index 88e79563d5..536abd31fb 100644
--- a/docs/attributes-registry/aws.md
+++ b/docs/attributes-registry/aws.md
@@ -65,6 +65,8 @@ This document defines attributes for AWS Elastic Container Service (ECS).
| `aws.ecs.task.id` | string | The ID of a running ECS task. The ID MUST be extracted from `task.arn`. | `10838bed-421f-43ef-870a-f43feacbbb5b`; `23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd` |  |
| `aws.ecs.task.revision` | string | The revision for the task definition used to create the ECS task. | `8`; `26` |  |
+---
+
`aws.ecs.launchtype` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/cicd.md b/docs/attributes-registry/cicd.md
index e4c03c3558..e42bf16360 100644
--- a/docs/attributes-registry/cicd.md
+++ b/docs/attributes-registry/cicd.md
@@ -19,6 +19,8 @@ This group describes attributes specific to pipelines within a Continuous Integr
| `cicd.pipeline.task.run.url.full` | string | The [URL](https://wikipedia.org/wiki/URL) of the pipeline run providing the complete address in order to locate and identify the pipeline run. | `https://github.com/open-telemetry/semantic-conventions/actions/runs/9753949763/job/26920038674?pr=1075` |  |
| `cicd.pipeline.task.type` | string | The type of the task within a pipeline. | `build`; `test`; `deploy` |  |
+---
+
`cicd.pipeline.task.type` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/cloud.md b/docs/attributes-registry/cloud.md
index 0a2dfd2236..ceb19dbf4e 100644
--- a/docs/attributes-registry/cloud.md
+++ b/docs/attributes-registry/cloud.md
@@ -43,6 +43,8 @@ The following well-known definitions MUST be used if you set this attribute and
This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share
a TracerProvider.
+---
+
`cloud.platform` 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.
| Value | Description | Stability |
@@ -76,6 +78,8 @@ The following well-known definitions MUST be used if you set this attribute and
| `tencent_cloud_eks` | Tencent Cloud Elastic Kubernetes Service (EKS) |  |
| `tencent_cloud_scf` | Tencent Cloud Serverless Cloud Function (SCF) |  |
+---
+
`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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/container.md b/docs/attributes-registry/container.md
index f571b02feb..578096de29 100644
--- a/docs/attributes-registry/container.md
+++ b/docs/attributes-registry/container.md
@@ -50,6 +50,8 @@ Describes deprecated container attributes.
| `container.cpu.state` | string | Deprecated, use `cpu.mode` instead. | `user`; `kernel` | 
Replaced by `cpu.mode` |
| `container.labels.` | string | Deprecated, use `container.label` instead. | `container.label.app=nginx` | 
Replaced by `container.label`. |
+---
+
`container.cpu.state` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/cpu.md b/docs/attributes-registry/cpu.md
index 70ea4139de..a2608e0deb 100644
--- a/docs/attributes-registry/cpu.md
+++ b/docs/attributes-registry/cpu.md
@@ -14,6 +14,8 @@ Attributes specific to a cpu instance.
|---|---|---|---|---|
| `cpu.mode` | string | The mode of the CPU | `user`; `system` |  |
+---
+
`cpu.mode` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md
index 927ce0f6f2..eb72e22f2b 100644
--- a/docs/attributes-registry/db.md
+++ b/docs/attributes-registry/db.md
@@ -91,6 +91,8 @@ This attribute has stability level RELEASE CANDIDATE.
**[9] `db.system`:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge.
This attribute has stability level RELEASE CANDIDATE.
+---
+
`db.client.connection.state` 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.
| Value | Description | Stability |
@@ -98,6 +100,8 @@ This attribute has stability level RELEASE CANDIDATE.
| `idle` | idle |  |
| `used` | used |  |
+---
+
`db.system` 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.
| Value | Description | Stability |
@@ -170,6 +174,8 @@ This group defines attributes for Cassandra.
| `db.cassandra.page_size` | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` |  |
| `db.cassandra.speculative_execution_count` | int | The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. | `0`; `2` |  |
+---
+
`db.cassandra.consistency_level` 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.
| Value | Description | Stability |
@@ -202,6 +208,8 @@ This group defines attributes for Azure Cosmos DB.
**[10] `db.cosmosdb.regions_contacted`:** Region name matches the format of `displayName` in [Azure Location API](https://learn.microsoft.com/rest/api/subscription/subscriptions/list-locations?view=rest-subscription-2021-10-01&tabs=HTTP#location)
+---
+
`db.cosmosdb.connection_mode` 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.
| Value | Description | Stability |
@@ -209,6 +217,8 @@ This group defines attributes for Azure Cosmos DB.
| `direct` | Direct connection. |  |
| `gateway` | Gateway (HTTP) connection. |  |
+---
+
`db.cosmosdb.consistency_level` 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.
| Value | Description | Stability |
@@ -254,6 +264,8 @@ This group defines attributes for Elasticsearch.
| `db.statement` | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | 
Replaced by `db.query.text`. |
| `db.user` | string | Deprecated, no replacement at this time. | `readonly_user`; `reporting_user` | 
No replacement at this time. |
+---
+
`db.cosmosdb.operation_type` 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.
| Value | Description | Stability |
@@ -285,6 +297,8 @@ This group defines attributes for Elasticsearch.
| `pool.name` | string | Deprecated, use `db.client.connection.pool.name` instead. | `myDataSource` | 
Replaced by `db.client.connection.pool.name`. |
| `state` | string | Deprecated, use `db.client.connection.state` instead. | `idle` | 
Replaced by `db.client.connection.state`. |
+---
+
`db.client.connections.state` 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.
| Value | Description | Stability |
@@ -292,6 +306,8 @@ This group defines attributes for Elasticsearch.
| `idle` | idle |  |
| `used` | used |  |
+---
+
`state` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/deployment.md b/docs/attributes-registry/deployment.md
index 25c3451d52..bda9350865 100644
--- a/docs/attributes-registry/deployment.md
+++ b/docs/attributes-registry/deployment.md
@@ -28,6 +28,8 @@ considered to be identifying the same service:
- `service.name=frontend`, `deployment.environment.name=production`
- `service.name=frontend`, `deployment.environment.name=staging`.
+---
+
`deployment.status` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/disk.md b/docs/attributes-registry/disk.md
index 3bd1c7ce5f..cb8a8bd267 100644
--- a/docs/attributes-registry/disk.md
+++ b/docs/attributes-registry/disk.md
@@ -14,6 +14,8 @@ These attributes may be used for any disk related operation.
|---|---|---|---|---|
| `disk.io.direction` | string | The disk IO operation direction. | `read` |  |
+---
+
`disk.io.direction` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/dotnet.md b/docs/attributes-registry/dotnet.md
index 0e806cbc49..75acc35161 100644
--- a/docs/attributes-registry/dotnet.md
+++ b/docs/attributes-registry/dotnet.md
@@ -14,6 +14,8 @@ This document defines .NET related attributes.
|---|---|---|---|---|
| `dotnet.gc.heap.generation` | string | Name of the garbage collector managed heap generation. | `gen0`; `gen1`; `gen2` |  |
+---
+
`dotnet.gc.heap.generation` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/error.md b/docs/attributes-registry/error.md
index 3867e83e66..ae3acc3717 100644
--- a/docs/attributes-registry/error.md
+++ b/docs/attributes-registry/error.md
@@ -34,6 +34,8 @@ it's RECOMMENDED to:
- Use a domain-specific attribute
- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
+---
+
`error.type` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/faas.md b/docs/attributes-registry/faas.md
index 18d2262822..24cbfd3cfe 100644
--- a/docs/attributes-registry/faas.md
+++ b/docs/attributes-registry/faas.md
@@ -66,6 +66,8 @@ definition of function name MUST be used for this attribute
[`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.
+---
+
`faas.document.operation` 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.
| Value | Description | Stability |
@@ -74,6 +76,8 @@ definition of function name MUST be used for this attribute
| `edit` | When an object is modified. |  |
| `insert` | When a new object is created. |  |
+---
+
`faas.invoked_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.
| Value | Description | Stability |
@@ -84,6 +88,8 @@ definition of function name MUST be used for this attribute
| `gcp` | Google Cloud Platform |  |
| `tencent_cloud` | Tencent Cloud |  |
+---
+
`faas.trigger` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md
index d61da8e405..19cc5666fb 100644
--- a/docs/attributes-registry/feature-flag.md
+++ b/docs/attributes-registry/feature-flag.md
@@ -29,6 +29,8 @@ for referring to a value without including the value itself. This can
provide additional context for understanding the meaning behind a value.
For example, the variant `red` maybe be used for the value `#c05543`.
+---
+
`feature_flag.evaluation.reason` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/gen-ai.md b/docs/attributes-registry/gen-ai.md
index 8f50b867c6..105ab4761f 100644
--- a/docs/attributes-registry/gen-ai.md
+++ b/docs/attributes-registry/gen-ai.md
@@ -45,6 +45,8 @@ is set to `openai` based on the instrumentation's best knowledge.
For custom model, a custom friendly name SHOULD be used.
If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
+---
+
`gen_ai.operation.name` 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.
| Value | Description | Stability |
@@ -52,6 +54,8 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+---
+
`gen_ai.system` 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.
| Value | Description | Stability |
@@ -64,6 +68,8 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
| `openai` | OpenAI |  |
| `vertex_ai` | Vertex AI |  |
+---
+
`gen_ai.token.type` 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.
| Value | Description | Stability |
@@ -83,6 +89,8 @@ Thie group defines attributes for OpenAI.
| `gen_ai.openai.response.service_tier` | string | The service tier used for the response. | `scale`; `default` |  |
| `gen_ai.openai.response.system_fingerprint` | string | A fingerprint to track any eventual change in the Generative AI environment. | `fp_44709d6fcb` |  |
+---
+
`gen_ai.openai.request.response_format` 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.
| Value | Description | Stability |
@@ -91,6 +99,8 @@ Thie group defines attributes for OpenAI.
| `json_schema` | JSON schema response format |  |
| `text` | Text response format |  |
+---
+
`gen_ai.openai.request.service_tier` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/geo.md b/docs/attributes-registry/geo.md
index 64440ee478..b6e424f764 100644
--- a/docs/attributes-registry/geo.md
+++ b/docs/attributes-registry/geo.md
@@ -21,6 +21,8 @@ Note: Geo attributes are typically used under another namespace, such as client.
| `geo.postal_code` | string | Postal code associated with the location. Values appropriate for this field may also be known as a postcode or ZIP code and will vary widely from country to country. | `94040` |  |
| `geo.region.iso_code` | string | Region ISO code ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)). | `CA-QC` |  |
+---
+
`geo.continent.code` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/go.md b/docs/attributes-registry/go.md
index d27bca24ce..5b781841eb 100644
--- a/docs/attributes-registry/go.md
+++ b/docs/attributes-registry/go.md
@@ -14,6 +14,8 @@ This document defines Go related attributes.
|---|---|---|---|---|
| `go.memory.type` | string | The type of memory. | `other`; `stack` |  |
+---
+
`go.memory.type` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/graphql.md b/docs/attributes-registry/graphql.md
index 81891eab73..e7741d3678 100644
--- a/docs/attributes-registry/graphql.md
+++ b/docs/attributes-registry/graphql.md
@@ -18,6 +18,8 @@ This document defines attributes for GraphQL.
**[1] `graphql.document`:** The value may be sanitized to exclude sensitive information.
+---
+
`graphql.operation.type` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/hardware.md b/docs/attributes-registry/hardware.md
index 443aea784a..2de9fa6500 100644
--- a/docs/attributes-registry/hardware.md
+++ b/docs/attributes-registry/hardware.md
@@ -20,6 +20,8 @@ Attributes for hardware.
**[1] `hw.type`:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`.
+---
+
`hw.state` 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.
| Value | Description | Stability |
@@ -28,6 +30,8 @@ Attributes for hardware.
| `failed` | Failed |  |
| `ok` | Ok |  |
+---
+
`hw.type` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/host.md b/docs/attributes-registry/host.md
index 4a21ab9b3a..27b77fae96 100644
--- a/docs/attributes-registry/host.md
+++ b/docs/attributes-registry/host.md
@@ -34,6 +34,8 @@ A host is defined as a computing instance. For example, physical servers, virtua
**[3] `host.mac`:** MAC Addresses MUST be represented in [IEEE RA hexadecimal form](https://standards.ieee.org/wp-content/uploads/import/documents/tutorials/eui.pdf): as hyphen-separated octets in uppercase hexadecimal form from most to least significant.
+---
+
`host.arch` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/http.md b/docs/attributes-registry/http.md
index 2d9e83ddff..79ce088da5 100644
--- a/docs/attributes-registry/http.md
+++ b/docs/attributes-registry/http.md
@@ -56,6 +56,8 @@ The attribute value MUST consist of either multiple header values as an array of
**[5] `http.route`:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
+---
+
`http.connection.state` 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.
| Value | Description | Stability |
@@ -63,6 +65,8 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
| `active` | active state. |  |
| `idle` | idle state. |  |
+---
+
`http.request.method` 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.
| Value | Description | Stability |
@@ -99,6 +103,8 @@ Describes deprecated HTTP attributes.
| `http.url` | string | Deprecated, use `url.full` instead. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | 
Replaced by `url.full`. |
| `http.user_agent` | string | Deprecated, use `user_agent.original` instead. | `CERN-LineMode/2.15 libwww/2.17b3`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1` | 
Replaced by `user_agent.original`. |
+---
+
`http.flavor` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/ios.md b/docs/attributes-registry/ios.md
index 784abe1e98..1bba11e215 100644
--- a/docs/attributes-registry/ios.md
+++ b/docs/attributes-registry/ios.md
@@ -16,6 +16,8 @@ The iOS platform on which the iOS application is running.
**[1] `ios.state`:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived.
+---
+
`ios.state` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/jvm.md b/docs/attributes-registry/jvm.md
index a503c44343..b604f44c02 100644
--- a/docs/attributes-registry/jvm.md
+++ b/docs/attributes-registry/jvm.md
@@ -28,6 +28,8 @@ This document defines Java Virtual machine related attributes.
**[4] `jvm.memory.pool.name`:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
+---
+
`jvm.memory.type` 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.
| Value | Description | Stability |
@@ -35,6 +37,8 @@ This document defines Java Virtual machine related attributes.
| `heap` | Heap memory. |  |
| `non_heap` | Non-heap memory |  |
+---
+
`jvm.thread.state` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/k8s.md b/docs/attributes-registry/k8s.md
index f62a09ec5f..784ab78b5e 100644
--- a/docs/attributes-registry/k8s.md
+++ b/docs/attributes-registry/k8s.md
@@ -65,6 +65,8 @@ Which states:
Therefore, UIDs between clusters should be extremely unlikely to
conflict.
+---
+
`k8s.volume.type` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/linux.md b/docs/attributes-registry/linux.md
index 82c90fe1fb..f6283d0193 100644
--- a/docs/attributes-registry/linux.md
+++ b/docs/attributes-registry/linux.md
@@ -14,6 +14,8 @@ Describes Linux Memory attributes
|---|---|---|---|---|
| `linux.memory.slab.state` | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` |  |
+---
+
`linux.memory.slab.state` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/log.md b/docs/attributes-registry/log.md
index c6ebd18ba7..aa1ab47139 100644
--- a/docs/attributes-registry/log.md
+++ b/docs/attributes-registry/log.md
@@ -18,6 +18,8 @@ This document defines log attributes
|---|---|---|---|---|
| `log.iostream` | string | The stream associated with the log. See below for a list of well-known values. | `stdout`; `stderr` |  |
+---
+
`log.iostream` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md
index ed78f163be..b21661f4df 100644
--- a/docs/attributes-registry/messaging.md
+++ b/docs/attributes-registry/messaging.md
@@ -59,6 +59,8 @@ size should be used.
**[9] `messaging.system`:** The actual messaging system may differ from the one known by the client. For example, when using Kafka client libraries to communicate with Azure Event Hubs, the `messaging.system` is set to `kafka` based on the instrumentation's best knowledge.
+---
+
`messaging.operation.type` 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.
| Value | Description | Stability |
@@ -71,6 +73,8 @@ size should be used.
| `send` | One or more messages are provided for sending to an intermediary. If a single message is sent, the context of the "Send" span can be used as the creation context and no "Create" span needs to be created. |  |
| `settle` | One or more messages are settled. |  |
+---
+
`messaging.system` 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.
| Value | Description | Stability |
@@ -142,6 +146,8 @@ This group describes attributes specific to RocketMQ.
| `messaging.rocketmq.message.type` | string | Type of message. | `normal`; `fifo`; `delay` |  |
| `messaging.rocketmq.namespace` | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` |  |
+---
+
`messaging.rocketmq.consumption_model` 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.
| Value | Description | Stability |
@@ -149,6 +155,8 @@ This group describes attributes specific to RocketMQ.
| `broadcasting` | Broadcasting consumption model |  |
| `clustering` | Clustering consumption model |  |
+---
+
`messaging.rocketmq.message.type` 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.
| Value | Description | Stability |
@@ -168,6 +176,8 @@ This group describes attributes specific to Azure Service Bus.
| `messaging.servicebus.message.delivery_count` | int | Number of deliveries that have been attempted for this message. | `2` |  |
| `messaging.servicebus.message.enqueued_time` | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` |  |
+---
+
`messaging.servicebus.disposition_status` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/network.md b/docs/attributes-registry/network.md
index ff9bec8852..9f5a64ee29 100644
--- a/docs/attributes-registry/network.md
+++ b/docs/attributes-registry/network.md
@@ -44,6 +44,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
**[4] `network.type`:** The value SHOULD be normalized to lowercase.
+---
+
`network.connection.subtype` 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.
| Value | Description | Stability |
@@ -70,6 +72,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `td_scdma` | TD-SCDMA |  |
| `umts` | UMTS |  |
+---
+
`network.connection.type` 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.
| Value | Description | Stability |
@@ -80,6 +84,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `wifi` | wifi |  |
| `wired` | wired |  |
+---
+
`network.io.direction` 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.
| Value | Description | Stability |
@@ -87,6 +93,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `receive` | receive |  |
| `transmit` | transmit |  |
+---
+
`network.transport` 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.
| Value | Description | Stability |
@@ -97,6 +105,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `udp` | UDP |  |
| `unix` | Unix domain socket |  |
+---
+
`network.type` 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.
| Value | Description | Stability |
@@ -126,6 +136,8 @@ These attributes may be used for any network related operation.
| `net.sock.peer.port` | int | Deprecated, use `network.peer.port`. | `65531` | 
Replaced by `network.peer.port`. |
| `net.transport` | string | Deprecated, use `network.transport`. | `ip_tcp`; `ip_udp`; `pipe` | 
Replaced by `network.transport`. |
+---
+
`net.sock.family` 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.
| Value | Description | Stability |
@@ -134,6 +146,8 @@ These attributes may be used for any network related operation.
| `inet6` | IPv6 address |  |
| `unix` | Unix domain socket path |  |
+---
+
`net.transport` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/nodejs.md b/docs/attributes-registry/nodejs.md
index 76cfd152e8..4ef8fee7e9 100644
--- a/docs/attributes-registry/nodejs.md
+++ b/docs/attributes-registry/nodejs.md
@@ -14,6 +14,8 @@ Describes Node.js related attributes.
|---|---|---|---|---|
| `nodejs.eventloop.state` | string | The state of event loop time. | `active`; `idle` |  |
+---
+
`nodejs.eventloop.state` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/opentracing.md b/docs/attributes-registry/opentracing.md
index ec1deb4087..e2a4080d8f 100644
--- a/docs/attributes-registry/opentracing.md
+++ b/docs/attributes-registry/opentracing.md
@@ -16,6 +16,8 @@ Attributes used by the OpenTracing Shim layer.
**[1] `opentracing.ref_type`:** The causal relationship between a child Span and a parent Span.
+---
+
`opentracing.ref_type` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/os.md b/docs/attributes-registry/os.md
index 9c1a841805..da36c11833 100644
--- a/docs/attributes-registry/os.md
+++ b/docs/attributes-registry/os.md
@@ -18,6 +18,8 @@ The operating system (OS) on which the process represented by this resource is r
| `os.type` | string | The operating system type. | `windows`; `linux`; `darwin` |  |
| `os.version` | string | The version string of the operating system as defined in [Version Attributes](/docs/resource/README.md#version-attributes). | `14.2.1`; `18.04.1` |  |
+---
+
`os.type` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md
index 44076a1e63..2c236b530e 100644
--- a/docs/attributes-registry/otel.md
+++ b/docs/attributes-registry/otel.md
@@ -19,6 +19,8 @@ Attributes reserved for OpenTelemetry
| `otel.status_code` | string | Name of the code, either "OK" or "ERROR". MUST NOT be set if the status code is UNSET. | `OK`; `ERROR` |  |
| `otel.status_description` | string | Description of the Status if it has a value, otherwise not set. | `resource not found` |  |
+---
+
`otel.status_code` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/process.md b/docs/attributes-registry/process.md
index d03020506f..994792206c 100644
--- a/docs/attributes-registry/process.md
+++ b/docs/attributes-registry/process.md
@@ -54,6 +54,8 @@ An operating system process.
**[3] `process.vpid`:** The process ID within a PID namespace. This is not necessarily unique across all processes on the host but it is unique within the process namespace that the process exists within.
+---
+
`process.context_switch_type` 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.
| Value | Description | Stability |
@@ -61,6 +63,8 @@ An operating system process.
| `involuntary` | involuntary |  |
| `voluntary` | voluntary |  |
+---
+
`process.paging.fault_type` 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.
| Value | Description | Stability |
@@ -77,6 +81,8 @@ Deprecated process attributes.
| `process.cpu.state` | string | Deprecated, use `cpu.mode` instead. | `system`; `user`; `wait` | 
Replaced by `cpu.mode` |
| `process.executable.build_id.profiling` | string | "Deprecated, use `process.executable.build_id.htlhash` instead." | `600DCAFE4A110000F2BF38C493F5FB92` | 
Replaced by `process.executable.build_id.htlhash` |
+---
+
`process.cpu.state` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/profile.md b/docs/attributes-registry/profile.md
index cb21193a68..266d316f4b 100644
--- a/docs/attributes-registry/profile.md
+++ b/docs/attributes-registry/profile.md
@@ -14,6 +14,8 @@ Describes the origin of a single frame in a Profile.
|---|---|---|---|---|
| `profile.frame.type` | string | Describes the interpreter or compiler of a single frame. | `cpython` |  |
+---
+
`profile.frame.type` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/rpc.md b/docs/attributes-registry/rpc.md
index 1639adb68e..52cf593508 100644
--- a/docs/attributes-registry/rpc.md
+++ b/docs/attributes-registry/rpc.md
@@ -47,6 +47,8 @@ This document defines attributes for remote procedure calls.
**[7] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`rpc.connect_rpc.error_code` 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.
| Value | Description | Stability |
@@ -68,6 +70,8 @@ This document defines attributes for remote procedure calls.
| `unimplemented` | unimplemented |  |
| `unknown` | unknown |  |
+---
+
`rpc.grpc.status_code` 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.
| Value | Description | Stability |
@@ -90,6 +94,8 @@ This document defines attributes for remote procedure calls.
| `15` | DATA_LOSS |  |
| `16` | UNAUTHENTICATED |  |
+---
+
`rpc.message.type` 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.
| Value | Description | Stability |
@@ -97,6 +103,8 @@ This document defines attributes for remote procedure calls.
| `RECEIVED` | received |  |
| `SENT` | sent |  |
+---
+
`rpc.system` 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.
| Value | Description | Stability |
@@ -118,6 +126,8 @@ Deprecated rpc message attributes.
| `message.type` | string | Deprecated, use `rpc.message.type` instead. | `SENT`; `RECEIVED` | 
Replaced by `rpc.message.type`. |
| `message.uncompressed_size` | int | Deprecated, use `rpc.message.uncompressed_size` instead. | | 
Replaced by `rpc.message.uncompressed_size`. |
+---
+
`message.type` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/signalr.md b/docs/attributes-registry/signalr.md
index d1535b3bf3..e2b6771ec6 100644
--- a/docs/attributes-registry/signalr.md
+++ b/docs/attributes-registry/signalr.md
@@ -15,6 +15,8 @@ SignalR attributes
| `signalr.connection.status` | string | SignalR HTTP connection closure status. | `app_shutdown`; `timeout` |  |
| `signalr.transport` | string | [SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md) | `web_sockets`; `long_polling` |  |
+---
+
`signalr.connection.status` 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.
| Value | Description | Stability |
@@ -23,6 +25,8 @@ SignalR attributes
| `normal_closure` | The connection was closed normally. |  |
| `timeout` | The connection was closed due to a timeout. |  |
+---
+
`signalr.transport` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/system.md b/docs/attributes-registry/system.md
index a94bda9e14..f327b42c42 100644
--- a/docs/attributes-registry/system.md
+++ b/docs/attributes-registry/system.md
@@ -42,6 +42,8 @@ Describes Filesystem attributes
| `system.filesystem.state` | string | The filesystem state | `used` |  |
| `system.filesystem.type` | string | The filesystem type | `ext4` |  |
+---
+
`system.filesystem.state` 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.
| Value | Description | Stability |
@@ -50,6 +52,8 @@ Describes Filesystem attributes
| `reserved` | reserved |  |
| `used` | used |  |
+---
+
`system.filesystem.type` 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.
| Value | Description | Stability |
@@ -69,6 +73,8 @@ Describes System Memory attributes
|---|---|---|---|---|
| `system.memory.state` | string | The memory state | `free`; `cached` |  |
+---
+
`system.memory.state` 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.
| Value | Description | Stability |
@@ -87,6 +93,8 @@ Describes Network attributes
|---|---|---|---|---|
| `system.network.state` | string | A stateless protocol MUST NOT set this attribute | `close_wait` |  |
+---
+
`system.network.state` 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.
| Value | Description | Stability |
@@ -114,6 +122,8 @@ Describes System Memory Paging attributes
| `system.paging.state` | string | The memory paging state | `free` |  |
| `system.paging.type` | string | The memory paging type | `minor` |  |
+---
+
`system.paging.direction` 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.
| Value | Description | Stability |
@@ -121,6 +131,8 @@ Describes System Memory Paging attributes
| `in` | in |  |
| `out` | out |  |
+---
+
`system.paging.state` 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.
| Value | Description | Stability |
@@ -128,6 +140,8 @@ Describes System Memory Paging attributes
| `free` | free |  |
| `used` | used |  |
+---
+
`system.paging.type` 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.
| Value | Description | Stability |
@@ -143,6 +157,8 @@ Describes System Process attributes
|---|---|---|---|---|
| `system.process.status` | string | The process state, e.g., [Linux Process State Codes](https://man7.org/linux/man-pages/man1/ps.1.html#PROCESS_STATE_CODES) | `running` |  |
+---
+
`system.process.status` 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.
| Value | Description | Stability |
@@ -161,6 +177,8 @@ Deprecated system attributes.
| `system.cpu.state` | string | Deprecated, use `cpu.mode` instead. | `idle`; `interrupt` | 
Replaced by `cpu.mode` |
| `system.processes.status` | string | Deprecated, use `system.process.status` instead. | `running` | 
Replaced by `system.process.status`. |
+---
+
`system.cpu.state` 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.
| Value | Description | Stability |
@@ -173,6 +191,8 @@ Deprecated system attributes.
| `system` | system |  |
| `user` | user |  |
+---
+
`system.processes.status` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/telemetry.md b/docs/attributes-registry/telemetry.md
index 6d619bbdb8..7c92cc2430 100644
--- a/docs/attributes-registry/telemetry.md
+++ b/docs/attributes-registry/telemetry.md
@@ -28,6 +28,8 @@ or another suitable identifier depending on the language.
The identifier `opentelemetry` is reserved and MUST NOT be used in this case.
All custom identifiers SHOULD be stable across different versions of an implementation.
+---
+
`telemetry.sdk.language` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/test.md b/docs/attributes-registry/test.md
index 0be8824c4b..4e1bc51118 100644
--- a/docs/attributes-registry/test.md
+++ b/docs/attributes-registry/test.md
@@ -17,6 +17,8 @@ This group describes attributes specific to [software tests](https://wikipedia.o
| `test.suite.name` | string | The human readable name of a [test suite](https://wikipedia.org/wiki/Test_suite). | `TestSuite1` |  |
| `test.suite.run.status` | string | The status of the test suite run. | `success`; `failure`; `skipped`; `aborted`; `timed_out`; `in_progress` |  |
+---
+
`test.case.result.status` 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.
| Value | Description | Stability |
@@ -24,6 +26,8 @@ This group describes attributes specific to [software tests](https://wikipedia.o
| `fail` | fail |  |
| `pass` | pass |  |
+---
+
`test.suite.run.status` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/tls.md b/docs/attributes-registry/tls.md
index 7465c25a96..76ea8724bb 100644
--- a/docs/attributes-registry/tls.md
+++ b/docs/attributes-registry/tls.md
@@ -46,6 +46,8 @@ This document defines semantic convention attributes in the TLS namespace.
**[1] `tls.cipher`:** The values allowed for `tls.cipher` MUST be one of the `Descriptions` of the [registered TLS Cipher Suits](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#table-tls-parameters-4).
+---
+
`tls.protocol.name` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/v8js.md b/docs/attributes-registry/v8js.md
index bb1ca488f3..90ebf86979 100644
--- a/docs/attributes-registry/v8js.md
+++ b/docs/attributes-registry/v8js.md
@@ -17,6 +17,8 @@ Describes V8 JS Engine Runtime related attributes.
**[1] `v8js.heap.space.name`:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics)
+---
+
`v8js.gc.type` 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.
| Value | Description | Stability |
@@ -26,6 +28,8 @@ Describes V8 JS Engine Runtime related attributes.
| `minor` | Minor (Scavenge). |  |
| `weakcb` | Weak Callbacks (Process Weak Callbacks). |  |
+---
+
`v8js.heap.space.name` 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.
| Value | Description | Stability |
diff --git a/docs/attributes-registry/vcs.md b/docs/attributes-registry/vcs.md
index d77403dc69..b418b16e83 100644
--- a/docs/attributes-registry/vcs.md
+++ b/docs/attributes-registry/vcs.md
@@ -49,6 +49,8 @@ it is identical to the `ref.head.name`, it SHOULD still be included. It is
up to the implementer to decide which value to set as the revision
based on the VCS system and situational context.
+---
+
`vcs.change.state` 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.
| Value | Description | Stability |
@@ -58,6 +60,8 @@ based on the VCS system and situational context.
| `open` | Open means the change is currently active and under review. It hasn't been merged into the target branch yet, and it's still possible to make changes or add comments. |  |
| `wip` | WIP (work-in-progress, draft) means the change is still in progress and not yet ready for a full review. It might still undergo significant changes. |  |
+---
+
`vcs.line_change.type` 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.
| Value | Description | Stability |
@@ -65,6 +69,8 @@ based on the VCS system and situational context.
| `added` | How many lines were added. |  |
| `removed` | How many lines were removed. |  |
+---
+
`vcs.ref.base.type` 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.
| Value | Description | Stability |
@@ -72,6 +78,8 @@ based on the VCS system and situational context.
| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) |  |
| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) |  |
+---
+
`vcs.ref.head.type` 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.
| Value | Description | Stability |
@@ -79,6 +87,8 @@ based on the VCS system and situational context.
| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) |  |
| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) |  |
+---
+
`vcs.ref.type` 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.
| Value | Description | Stability |
@@ -86,6 +96,8 @@ based on the VCS system and situational context.
| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) |  |
| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) |  |
+---
+
`vcs.revision_delta.direction` 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.
| Value | Description | Stability |
@@ -105,6 +117,8 @@ based on the VCS system and situational context.
| `vcs.repository.ref.revision` | string | Deprecated, use `vcs.ref.head.revision` instead. | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | 
Deprecated, use `vcs.ref.head.revision` instead. |
| `vcs.repository.ref.type` | string | Deprecated, use `vcs.ref.head.type` instead. | `branch`; `tag` | 
Deprecated, use `vcs.ref.head.type` instead. |
+---
+
`vcs.repository.ref.type` 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.
| Value | Description | Stability |
diff --git a/docs/cicd/cicd-metrics.md b/docs/cicd/cicd-metrics.md
index a0b3244681..621ba0bbc8 100644
--- a/docs/cicd/cicd-metrics.md
+++ b/docs/cicd/cicd-metrics.md
@@ -50,6 +50,8 @@ This metric is [recommended][MetricRecommended].
| [`vcs.change.state`](/docs/attributes-registry/vcs.md) | string | The state of the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | `Required` |  |
| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+---
+
`vcs.change.state` 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.
| Value | Description | Stability |
@@ -85,6 +87,8 @@ This metric is [recommended][MetricRecommended].
| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` |  |
| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+---
+
`vcs.change.state` 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.
| Value | Description | Stability |
@@ -164,6 +168,8 @@ This metric is [recommended][MetricRecommended].
| [`vcs.ref.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` |  |
| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+---
+
`vcs.ref.type` 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.
| Value | Description | Stability |
@@ -205,6 +211,8 @@ If number of lines added/removed should be calculated from the start of time, th
| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
| [`vcs.change.id`](/docs/attributes-registry/vcs.md) | string | The ID of the change (pull request/merge request/changelist) if applicable. This is usually a unique (within repository) identifier generated by the VCS system. | `123` | `Conditionally Required` if a change is associate with the ref. |  |
+---
+
`vcs.line_change.type` 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.
| Value | Description | Stability |
@@ -212,6 +220,8 @@ If number of lines added/removed should be calculated from the start of time, th
| `added` | How many lines were added. |  |
| `removed` | How many lines were removed. |  |
+---
+
`vcs.ref.base.type` 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.
| Value | Description | Stability |
@@ -219,6 +229,8 @@ If number of lines added/removed should be calculated from the start of time, th
| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) |  |
| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) |  |
+---
+
`vcs.ref.head.type` 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.
| Value | Description | Stability |
@@ -259,6 +271,8 @@ instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers)
| [`vcs.revision_delta.direction`](/docs/attributes-registry/vcs.md) | string | The type of revision comparison. | `ahead`; `behind` | `Required` |  |
| [`vcs.change.id`](/docs/attributes-registry/vcs.md) | string | The ID of the change (pull request/merge request/changelist) if applicable. This is usually a unique (within repository) identifier generated by the VCS system. | `123` | `Conditionally Required` if a change is associate with the ref. |  |
+---
+
`vcs.ref.base.type` 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.
| Value | Description | Stability |
@@ -266,6 +280,8 @@ instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers)
| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) |  |
| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) |  |
+---
+
`vcs.ref.head.type` 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.
| Value | Description | Stability |
@@ -273,6 +289,8 @@ instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers)
| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) |  |
| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) |  |
+---
+
`vcs.revision_delta.direction` 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.
| Value | Description | Stability |
@@ -306,6 +324,8 @@ This metric is [recommended][MetricRecommended].
| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` |  |
| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+---
+
`vcs.ref.head.type` 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.
| Value | Description | Stability |
diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md
index b532fae2d9..8be12e8172 100644
--- a/docs/cloud-providers/aws-sdk.md
+++ b/docs/cloud-providers/aws-sdk.md
@@ -42,6 +42,8 @@ with the naming guidelines for RPC client spans.
**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`rpc.system` 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.
| Value | Description | Stability |
diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md
index d178b576d7..ccd22f2b36 100644
--- a/docs/database/cassandra.md
+++ b/docs/database/cassandra.md
@@ -132,6 +132,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`db.cassandra.consistency_level` 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.
| Value | Description | Stability |
@@ -148,6 +150,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `three` | three |  |
| `two` | two |  |
+---
+
`error.type` 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.
| Value | Description | Stability |
diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md
index 0247ef7372..f2d77b26bc 100644
--- a/docs/database/cosmosdb.md
+++ b/docs/database/cosmosdb.md
@@ -243,6 +243,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`db.cosmosdb.connection_mode` 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.
| Value | Description | Stability |
@@ -250,6 +252,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `direct` | Direct connection. |  |
| `gateway` | Gateway (HTTP) connection. |  |
+---
+
`db.cosmosdb.consistency_level` 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.
| Value | Description | Stability |
@@ -260,6 +264,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `Session` | session |  |
| `Strong` | strong |  |
+---
+
`error.type` 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.
| Value | Description | Stability |
@@ -387,6 +393,8 @@ Instrumentations SHOULD document how `error.type` is populated.
**[10] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+---
+
`db.cosmosdb.consistency_level` 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.
| Value | Description | Stability |
@@ -397,6 +405,8 @@ Instrumentations SHOULD document how `error.type` is populated.
| `Session` | session |  |
| `Strong` | strong |  |
+---
+
`error.type` 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.
| Value | Description | Stability |
diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md
index fe57cd4479..c95784e085 100644
--- a/docs/database/couchdb.md
+++ b/docs/database/couchdb.md
@@ -58,6 +58,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md
index b2a5cab8ae..858cec0a7f 100644
--- a/docs/database/database-metrics.md
+++ b/docs/database/database-metrics.md
@@ -169,6 +169,8 @@ For batch operations, if the individual operations are known to have the same qu
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
+---
+
`db.system` 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.
| Value | Description | Stability |
@@ -223,6 +225,8 @@ This attribute has stability level RELEASE CANDIDATE.
| `trino` | Trino |  |
| `vertica` | Vertica |  |
+---
+
`error.type` 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.
| Value | Description | Stability |
@@ -354,6 +358,8 @@ For batch operations, if the individual operations are known to have the same qu
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
+---
+
`db.system` 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.
| Value | Description | Stability |
@@ -408,6 +414,8 @@ This attribute has stability level RELEASE CANDIDATE.
| `trino` | Trino |  |
| `vertica` | Vertica |  |
+---
+
`error.type` 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.
| Value | Description | Stability |
@@ -443,6 +451,8 @@ This metric is [required][MetricRequired].
| [`db.client.connection.pool.name`](/docs/attributes-registry/db.md) | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation SHOULD use a combination of parameters that would make the name unique, for example, combining attributes `server.address`, `server.port`, and `db.namespace`, formatted as `server.address:server.port/db.namespace`. Instrumentations that generate connection pool name following different patterns SHOULD document it. | `myDataSource` | `Required` |  |
| [`db.client.connection.state`](/docs/attributes-registry/db.md) | string | The state of a connection in the pool | `idle` | `Required` |  |
+---
+
`db.client.connection.state` 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.
| Value | Description | Stability |
diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md
index 9792853b28..995b058697 100644
--- a/docs/database/database-spans.md
+++ b/docs/database/database-spans.md
@@ -209,6 +209,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`db.system` 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.
| Value | Description | Stability |
@@ -263,6 +265,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `trino` | Trino |  |
| `vertica` | Vertica |  |
+---
+
`error.type` 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.
| Value | Description | Stability |
diff --git a/docs/database/dynamodb.md b/docs/database/dynamodb.md
index 30f4d496b3..14d7ce3425 100644
--- a/docs/database/dynamodb.md
+++ b/docs/database/dynamodb.md
@@ -33,6 +33,8 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`rpc.system` 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.
| Value | Description | Stability |
@@ -71,6 +73,8 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`rpc.system` 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.
| Value | Description | Stability |
@@ -113,6 +117,8 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`rpc.system` 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.
| Value | Description | Stability |
@@ -151,6 +157,8 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`rpc.system` 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.
| Value | Description | Stability |
@@ -187,6 +195,8 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`rpc.system` 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.
| Value | Description | Stability |
@@ -223,6 +233,8 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`rpc.system` 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.
| Value | Description | Stability |
@@ -262,6 +274,8 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`rpc.system` 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.
| Value | Description | Stability |
@@ -300,6 +314,8 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`rpc.system` 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.
| Value | Description | Stability |
@@ -338,6 +354,8 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`rpc.system` 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.
| Value | Description | Stability |
@@ -382,6 +400,8 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`rpc.system` 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.
| Value | Description | Stability |
@@ -429,6 +449,8 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`rpc.system` 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.
| Value | Description | Stability |
@@ -467,6 +489,8 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`rpc.system` 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.
| Value | Description | Stability |
@@ -508,6 +532,8 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
**[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`rpc.system` 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.
| Value | Description | Stability |
diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md
index 6ba8bf57fb..34582635b0 100644
--- a/docs/database/elasticsearch.md
+++ b/docs/database/elasticsearch.md
@@ -124,12 +124,16 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.port`](/docs/attributes-registry/server.md)
* [`url.full`](/docs/attributes-registry/url.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`http.request.method` 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.
| Value | Description | Stability |
diff --git a/docs/database/hbase.md b/docs/database/hbase.md
index a7a94ece17..e4bdb17443 100644
--- a/docs/database/hbase.md
+++ b/docs/database/hbase.md
@@ -78,6 +78,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md
index 8cb960584c..b78e0f3edf 100644
--- a/docs/database/mariadb.md
+++ b/docs/database/mariadb.md
@@ -145,6 +145,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md
index 6f0bbb54d8..cfba85f15f 100644
--- a/docs/database/mongodb.md
+++ b/docs/database/mongodb.md
@@ -76,6 +76,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
diff --git a/docs/database/mssql.md b/docs/database/mssql.md
index 078d7bd848..8fea8253e7 100644
--- a/docs/database/mssql.md
+++ b/docs/database/mssql.md
@@ -115,6 +115,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
diff --git a/docs/database/mysql.md b/docs/database/mysql.md
index f53f35ae16..9124813138 100644
--- a/docs/database/mysql.md
+++ b/docs/database/mysql.md
@@ -145,6 +145,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md
index cf5736fe5f..6dbeba3292 100644
--- a/docs/database/postgresql.md
+++ b/docs/database/postgresql.md
@@ -152,6 +152,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
diff --git a/docs/database/redis.md b/docs/database/redis.md
index 599ab64c7d..a7b111bc4e 100644
--- a/docs/database/redis.md
+++ b/docs/database/redis.md
@@ -104,6 +104,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
diff --git a/docs/database/sql.md b/docs/database/sql.md
index af808272f2..481aea78b2 100644
--- a/docs/database/sql.md
+++ b/docs/database/sql.md
@@ -176,6 +176,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
diff --git a/docs/dns/dns-metrics.md b/docs/dns/dns-metrics.md
index 2abf5a5278..43c8e0401a 100644
--- a/docs/dns/dns-metrics.md
+++ b/docs/dns/dns-metrics.md
@@ -47,6 +47,8 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
**[2] `error.type`:** Instrumentations SHOULD use error code such as one of errors reported by `getaddrinfo`([Linux or other POSIX systems](https://man7.org/linux/man-pages/man3/getaddrinfo.3.html) / [Windows](https://learn.microsoft.com/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo)) or one reported by the runtime or client library. If error code is not available, the full name of exception type SHOULD be used.
+---
+
`error.type` 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.
| Value | Description | Stability |
diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md
index 10213cb41c..7ea3650573 100644
--- a/docs/dotnet/dotnet-aspnetcore-metrics.md
+++ b/docs/dotnet/dotnet-aspnetcore-metrics.md
@@ -54,6 +54,8 @@ All routing metrics are reported by the `Microsoft.AspNetCore.Routing` meter.
**[1] `http.route`:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
+---
+
`aspnetcore.routing.match_status` 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.
| Value | Description | Stability |
@@ -113,6 +115,8 @@ it's RECOMMENDED to:
**[2] `aspnetcore.diagnostics.handler.type`:** if and only if the exception was handled by this handler.
+---
+
`aspnetcore.diagnostics.exception.result` 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.
| Value | Description | Stability |
@@ -122,6 +126,8 @@ it's RECOMMENDED to:
| `skipped` | Exception handling was skipped because the response had started. |  |
| `unhandled` | Exception was not handled by the exception handling middleware. |  |
+---
+
`error.type` 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.
| Value | Description | Stability |
@@ -245,6 +251,8 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
**[1] `aspnetcore.rate_limiting.policy`:** if the matched endpoint for the request had a rate-limiting policy.
+---
+
`aspnetcore.rate_limiting.result` 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.
| Value | Description | Stability |
@@ -286,6 +294,8 @@ Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0
**[1] `aspnetcore.rate_limiting.policy`:** if the matched endpoint for the request had a rate-limiting policy.
+---
+
`aspnetcore.rate_limiting.result` 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.
| Value | Description | Stability |
diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md
index 236613ed37..4f61ba5e1c 100644
--- a/docs/dotnet/dotnet-kestrel-metrics.md
+++ b/docs/dotnet/dotnet-kestrel-metrics.md
@@ -64,6 +64,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+---
+
`network.transport` 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.
| Value | Description | Stability |
@@ -74,6 +76,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `udp` | UDP |  |
| `unix` | Unix domain socket |  |
+---
+
`network.type` 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.
| Value | Description | Stability |
@@ -184,12 +188,16 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`network.transport` 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.
| Value | Description | Stability |
@@ -200,6 +208,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `udp` | UDP |  |
| `unix` | Unix domain socket |  |
+---
+
`network.type` 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.
| Value | Description | Stability |
@@ -247,6 +257,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+---
+
`network.transport` 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.
| Value | Description | Stability |
@@ -257,6 +269,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `udp` | UDP |  |
| `unix` | Unix domain socket |  |
+---
+
`network.type` 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.
| Value | Description | Stability |
@@ -303,6 +317,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+---
+
`network.transport` 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.
| Value | Description | Stability |
@@ -313,6 +329,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `udp` | UDP |  |
| `unix` | Unix domain socket |  |
+---
+
`network.type` 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.
| Value | Description | Stability |
@@ -365,6 +383,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+---
+
`network.transport` 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.
| Value | Description | Stability |
@@ -375,6 +395,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `udp` | UDP |  |
| `unix` | Unix domain socket |  |
+---
+
`network.type` 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.
| Value | Description | Stability |
@@ -423,6 +445,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+---
+
`network.transport` 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.
| Value | Description | Stability |
@@ -433,6 +457,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `udp` | UDP |  |
| `unix` | Unix domain socket |  |
+---
+
`network.type` 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.
| Value | Description | Stability |
@@ -487,12 +513,16 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
**[5] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`network.transport` 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.
| Value | Description | Stability |
@@ -503,6 +533,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `udp` | UDP |  |
| `unix` | Unix domain socket |  |
+---
+
`network.type` 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.
| Value | Description | Stability |
@@ -549,6 +581,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+---
+
`network.transport` 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.
| Value | Description | Stability |
@@ -559,6 +593,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `udp` | UDP |  |
| `unix` | Unix domain socket |  |
+---
+
`network.type` 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.
| Value | Description | Stability |
diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md
index d398ef6780..91697e65e5 100644
--- a/docs/dotnet/dotnet-signalr-metrics.md
+++ b/docs/dotnet/dotnet-signalr-metrics.md
@@ -39,6 +39,8 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
| [`signalr.connection.status`](/docs/attributes-registry/signalr.md) | string | SignalR HTTP connection closure status. | `app_shutdown`; `timeout` | `Recommended` |  |
| [`signalr.transport`](/docs/attributes-registry/signalr.md) | string | [SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md) | `web_sockets`; `long_polling` | `Recommended` |  |
+---
+
`signalr.connection.status` 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.
| Value | Description | Stability |
@@ -47,6 +49,8 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
| `normal_closure` | The connection was closed normally. |  |
| `timeout` | The connection was closed due to a timeout. |  |
+---
+
`signalr.transport` 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.
| Value | Description | Stability |
@@ -80,6 +84,8 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
| [`signalr.connection.status`](/docs/attributes-registry/signalr.md) | string | SignalR HTTP connection closure status. | `app_shutdown`; `timeout` | `Recommended` |  |
| [`signalr.transport`](/docs/attributes-registry/signalr.md) | string | [SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md) | `web_sockets`; `long_polling` | `Recommended` |  |
+---
+
`signalr.connection.status` 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.
| Value | Description | Stability |
@@ -88,6 +94,8 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
| `normal_closure` | The connection was closed normally. |  |
| `timeout` | The connection was closed due to a timeout. |  |
+---
+
`signalr.transport` 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.
| Value | Description | Stability |
diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md
index d6dbb135c9..b14871df76 100644
--- a/docs/faas/faas-metrics.md
+++ b/docs/faas/faas-metrics.md
@@ -64,6 +64,8 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
|---|---|---|---|---|---|
| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` |  |
+---
+
`faas.trigger` 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.
| Value | Description | Stability |
@@ -102,6 +104,8 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
|---|---|---|---|---|---|
| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` |  |
+---
+
`faas.trigger` 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.
| Value | Description | Stability |
@@ -136,6 +140,8 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` |  |
+---
+
`faas.trigger` 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.
| Value | Description | Stability |
@@ -170,6 +176,8 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` |  |
+---
+
`faas.trigger` 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.
| Value | Description | Stability |
@@ -204,6 +212,8 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` |  |
+---
+
`faas.trigger` 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.
| Value | Description | Stability |
@@ -238,6 +248,8 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` |  |
+---
+
`faas.trigger` 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.
| Value | Description | Stability |
@@ -272,6 +284,8 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` |  |
+---
+
`faas.trigger` 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.
| Value | Description | Stability |
@@ -310,6 +324,8 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
|---|---|---|---|---|---|
| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` |  |
+---
+
`faas.trigger` 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.
| Value | Description | Stability |
@@ -344,6 +360,8 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` |  |
+---
+
`faas.trigger` 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.
| Value | Description | Stability |
diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md
index c5d4f9c53b..b49ee5766c 100644
--- a/docs/faas/faas-spans.md
+++ b/docs/faas/faas-spans.md
@@ -79,6 +79,8 @@ 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).
+---
+
`faas.trigger` 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.
| Value | Description | Stability |
@@ -151,6 +153,8 @@ 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).
+---
+
`faas.trigger` 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.
| Value | Description | Stability |
@@ -209,6 +213,8 @@ which the invoked FaaS instance reports about itself, if it's instrumented.
**[4] `faas.invoked_region`:** For some cloud providers, like AWS or GCP, the region in which a function is hosted is essential to uniquely identify the function and also part of its endpoint. Since it's part of the endpoint being called, the region is always known to clients. In these cases, `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional.
+---
+
`faas.invoked_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.
| Value | Description | Stability |
@@ -250,6 +256,8 @@ FaaS instrumentations that produce `faas` spans with trigger `datasource`, SHOUL
| [`faas.document.name`](/docs/attributes-registry/faas.md) | string | The document name/table subjected to the operation. For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table name. | `myFile.txt`; `myTableName` | `Recommended` |  |
| [`faas.document.time`](/docs/attributes-registry/faas.md) | string | A string containing the time when the data was accessed in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | `Recommended` |  |
+---
+
`faas.document.operation` 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.
| Value | Description | Stability |
diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md
index fbeae201fd..fcebce470c 100644
--- a/docs/feature-flags/feature-flags-logs.md
+++ b/docs/feature-flags/feature-flags-logs.md
@@ -92,12 +92,16 @@ For example, the variant `red` maybe be used for the value `#c05543`.
**[5] `feature_flag.evaluation.error.message`:** If and only if an error occurred. It's NOT RECOMMENDED to duplicate the value of `error.type` in `feature_flag.evaluation.error.message`.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`feature_flag.evaluation.reason` 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.
| Value | Description | Stability |
diff --git a/docs/gen-ai/azure-ai-inference.md b/docs/gen-ai/azure-ai-inference.md
index 8820b2cd40..1efd3ed907 100644
--- a/docs/gen-ai/azure-ai-inference.md
+++ b/docs/gen-ai/azure-ai-inference.md
@@ -57,12 +57,16 @@ Instrumentations SHOULD document the list of errors they report.
**[7] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`gen_ai.operation.name` 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.
| Value | Description | Stability |
diff --git a/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md
index 5870694ec7..be2ded85e5 100644
--- a/docs/gen-ai/gen-ai-events.md
+++ b/docs/gen-ai/gen-ai-events.md
@@ -75,6 +75,8 @@ is set to `openai` based on the instrumentation's best knowledge.
For custom model, a custom friendly name SHOULD be used.
If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
+---
+
`gen_ai.system` 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.
| Value | Description | Stability |
diff --git a/docs/gen-ai/gen-ai-metrics.md b/docs/gen-ai/gen-ai-metrics.md
index 6f5d09d9d9..126e1f75d9 100644
--- a/docs/gen-ai/gen-ai-metrics.md
+++ b/docs/gen-ai/gen-ai-metrics.md
@@ -85,6 +85,8 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
**[4] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+---
+
`gen_ai.operation.name` 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.
| Value | Description | Stability |
@@ -92,6 +94,8 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+---
+
`gen_ai.system` 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.
| Value | Description | Stability |
@@ -104,6 +108,8 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
| `openai` | OpenAI |  |
| `vertex_ai` | Vertex AI |  |
+---
+
`gen_ai.token.type` 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.
| Value | Description | Stability |
@@ -163,12 +169,16 @@ Instrumentations SHOULD document the list of errors they report.
**[5] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`gen_ai.operation.name` 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.
| Value | Description | Stability |
@@ -176,6 +186,8 @@ Instrumentations SHOULD document the list of errors they report.
| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+---
+
`gen_ai.system` 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.
| Value | Description | Stability |
@@ -247,12 +259,16 @@ Instrumentations SHOULD document the list of errors they report.
**[5] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`gen_ai.operation.name` 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.
| Value | Description | Stability |
@@ -260,6 +276,8 @@ Instrumentations SHOULD document the list of errors they report.
| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+---
+
`gen_ai.system` 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.
| Value | Description | Stability |
@@ -326,6 +344,8 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
**[4] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+---
+
`gen_ai.operation.name` 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.
| Value | Description | Stability |
@@ -333,6 +353,8 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+---
+
`gen_ai.system` 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.
| Value | Description | Stability |
@@ -398,6 +420,8 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
**[4] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+---
+
`gen_ai.operation.name` 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.
| Value | Description | Stability |
@@ -405,6 +429,8 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+---
+
`gen_ai.system` 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.
| Value | Description | Stability |
diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md
index a05a0993cf..dee6688b6a 100644
--- a/docs/gen-ai/gen-ai-spans.md
+++ b/docs/gen-ai/gen-ai-spans.md
@@ -86,12 +86,16 @@ Instrumentations SHOULD document the list of errors they report.
**[7] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`gen_ai.operation.name` 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.
| Value | Description | Stability |
@@ -99,6 +103,8 @@ Instrumentations SHOULD document the list of errors they report.
| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+---
+
`gen_ai.system` 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.
| Value | Description | Stability |
diff --git a/docs/gen-ai/openai.md b/docs/gen-ai/openai.md
index 12287b6e9f..1842f68e7f 100644
--- a/docs/gen-ai/openai.md
+++ b/docs/gen-ai/openai.md
@@ -76,12 +76,16 @@ Instrumentations SHOULD document the list of errors they report.
**[8] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`gen_ai.openai.request.response_format` 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.
| Value | Description | Stability |
@@ -90,6 +94,8 @@ Instrumentations SHOULD document the list of errors they report.
| `json_schema` | JSON schema response format |  |
| `text` | Text response format |  |
+---
+
`gen_ai.openai.request.service_tier` 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.
| Value | Description | Stability |
@@ -97,6 +103,8 @@ Instrumentations SHOULD document the list of errors they report.
| `auto` | The system will utilize scale tier credits until they are exhausted. |  |
| `default` | The system will utilize the default scale tier. |  |
+---
+
`gen_ai.operation.name` 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.
| Value | Description | Stability |
diff --git a/docs/general/attributes.md b/docs/general/attributes.md
index d0d5024933..601b43101d 100644
--- a/docs/general/attributes.md
+++ b/docs/general/attributes.md
@@ -226,6 +226,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
**[4] `network.type`:** The value SHOULD be normalized to lowercase.
+---
+
`network.transport` 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.
| Value | Description | Stability |
@@ -236,6 +238,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `udp` | UDP |  |
| `unix` | Unix domain socket |  |
+---
+
`network.type` 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.
| Value | Description | Stability |
@@ -305,6 +309,8 @@ Note that `network.local.*` attributes are not included in these examples since
| [`network.connection.subtype`](/docs/attributes-registry/network.md) | string | This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. | `LTE` | `Recommended` |  |
| [`network.connection.type`](/docs/attributes-registry/network.md) | string | The internet connection type. | `wifi` | `Recommended` |  |
+---
+
`network.connection.subtype` 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.
| Value | Description | Stability |
@@ -331,6 +337,8 @@ Note that `network.local.*` attributes are not included in these examples since
| `td_scdma` | TD-SCDMA |  |
| `umts` | UMTS |  |
+---
+
`network.connection.type` 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.
| Value | Description | Stability |
diff --git a/docs/general/logs.md b/docs/general/logs.md
index 3e350512a5..eeaa529605 100644
--- a/docs/general/logs.md
+++ b/docs/general/logs.md
@@ -103,6 +103,8 @@ As such, these should be recorded as Log Record attributes when applicable. They
|---|---|---|---|---|---|
| [`log.iostream`](/docs/attributes-registry/log.md) | string | The stream associated with the log. See below for a list of well-known values. | `stdout`; `stderr` | `Opt-In` |  |
+---
+
`log.iostream` 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.
| Value | Description | Stability |
diff --git a/docs/general/profiles.md b/docs/general/profiles.md
index 5a6c0f3666..ed7d59c9df 100644
--- a/docs/general/profiles.md
+++ b/docs/general/profiles.md
@@ -30,6 +30,8 @@ They may be used in any Profiles record they apply to.
|---|---|---|---|---|---|
| [`profile.frame.type`](/docs/attributes-registry/profile.md) | string | Describes the interpreter or compiler of a single frame. | `cpython` | `Recommended` |  |
+---
+
`profile.frame.type` 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.
| Value | Description | Stability |
diff --git a/docs/general/trace-compatibility.md b/docs/general/trace-compatibility.md
index ce48cfb79c..914c3f9cf7 100644
--- a/docs/general/trace-compatibility.md
+++ b/docs/general/trace-compatibility.md
@@ -37,6 +37,8 @@ between a child Span and a parent Span, as defined by
**[1] `opentracing.ref_type`:** The causal relationship between a child Span and a parent Span.
+---
+
`opentracing.ref_type` 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.
| Value | Description | Stability |
diff --git a/docs/graphql/graphql-spans.md b/docs/graphql/graphql-spans.md
index 1bc341996b..6d74464d95 100644
--- a/docs/graphql/graphql-spans.md
+++ b/docs/graphql/graphql-spans.md
@@ -37,6 +37,8 @@ the span SHOULD be named `GraphQL Operation`.
**[1] `graphql.document`:** The value may be sanitized to exclude sensitive information.
+---
+
`graphql.operation.type` 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.
| Value | Description | Stability |
diff --git a/docs/hardware/common.md b/docs/hardware/common.md
index d71c418558..1cd19a999b 100644
--- a/docs/hardware/common.md
+++ b/docs/hardware/common.md
@@ -42,6 +42,8 @@ monitored component:
**[1] `hw.type`:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`.
+---
+
`hw.type` 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.
| Value | Description | Stability |
@@ -90,6 +92,8 @@ This metric is [recommended][MetricRecommended].
**[1] `hw.type`:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`.
+---
+
`hw.type` 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.
| Value | Description | Stability |
@@ -141,12 +145,16 @@ This metric is [recommended][MetricRecommended].
**[2] `error.type`:** The `error.type` SHOULD match the error code reported by the component, the canonical name of the error, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`hw.type` 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.
| Value | Description | Stability |
@@ -197,6 +205,8 @@ This metric is [recommended][MetricRecommended].
**[1] `hw.type`:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`.
+---
+
`hw.type` 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.
| Value | Description | Stability |
@@ -248,6 +258,8 @@ This metric is [recommended][MetricRecommended].
**[1] `hw.type`:** Describes the category of the hardware component for which `hw.state` is being reported. For example, `hw.type=temperature` along with `hw.state=degraded` would indicate that the temperature of the hardware component has been reported as `degraded`.
+---
+
`hw.state` 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.
| Value | Description | Stability |
@@ -256,6 +268,8 @@ This metric is [recommended][MetricRecommended].
| `failed` | Failed |  |
| `ok` | Ok |  |
+---
+
`hw.type` 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.
| Value | Description | Stability |
diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md
index 0a094fe0e6..60020b3a9d 100644
--- a/docs/http/http-metrics.md
+++ b/docs/http/http-metrics.md
@@ -143,12 +143,16 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
> Since this attribute is based on HTTP headers, opting in to it may allow an attacker
> to trigger cardinality limits, degrading the usefulness of the metric.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`http.request.method` 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.
| Value | Description | Stability |
@@ -216,6 +220,8 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
> Since this attribute is based on HTTP headers, opting in to it may allow an attacker
> to trigger cardinality limits, degrading the usefulness of the metric.
+---
+
`http.request.method` 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.
| Value | Description | Stability |
@@ -318,12 +324,16 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
> Since this attribute is based on HTTP headers, opting in to it may allow an attacker
> to trigger cardinality limits, degrading the usefulness of the metric.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`http.request.method` 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.
| Value | Description | Stability |
@@ -426,12 +436,16 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
> Since this attribute is based on HTTP headers, opting in to it may allow an attacker
> to trigger cardinality limits, degrading the usefulness of the metric.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`http.request.method` 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.
| Value | Description | Stability |
@@ -531,12 +545,16 @@ If the request has completed successfully, instrumentations SHOULD NOT set `erro
**[8] `url.template`:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`http.request.method` 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.
| Value | Description | Stability |
@@ -630,12 +648,16 @@ If the request has completed successfully, instrumentations SHOULD NOT set `erro
**[8] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`http.request.method` 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.
| Value | Description | Stability |
@@ -729,12 +751,16 @@ If the request has completed successfully, instrumentations SHOULD NOT set `erro
**[8] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`http.request.method` 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.
| Value | Description | Stability |
@@ -785,6 +811,8 @@ This metric is optional.
**[3] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
+---
+
`http.connection.state` 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.
| Value | Description | Stability |
@@ -881,6 +909,8 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
+---
+
`http.request.method` 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.
| Value | Description | Stability |
diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md
index 6dbd01c9b6..045a69a408 100644
--- a/docs/http/http-spans.md
+++ b/docs/http/http-spans.md
@@ -253,12 +253,16 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.port`](/docs/attributes-registry/server.md)
* [`url.full`](/docs/attributes-registry/url.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`http.request.method` 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.
| Value | Description | Stability |
@@ -274,6 +278,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `PUT` | PUT method. |  |
| `TRACE` | TRACE method. |  |
+---
+
`network.transport` 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.
| Value | Description | Stability |
@@ -498,12 +504,16 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`url.scheme`](/docs/attributes-registry/url.md)
* [`user_agent.original`](/docs/attributes-registry/user-agent.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`http.request.method` 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.
| Value | Description | Stability |
@@ -519,6 +529,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `PUT` | PUT method. |  |
| `TRACE` | TRACE method. |  |
+---
+
`network.transport` 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.
| Value | Description | Stability |
diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md
index 7c8a26aa92..34bf545fab 100644
--- a/docs/messaging/azure-messaging.md
+++ b/docs/messaging/azure-messaging.md
@@ -124,12 +124,16 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`messaging.operation.type` 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.
| Value | Description | Stability |
@@ -140,6 +144,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `send` | One or more messages are provided for sending to an intermediary. If a single message is sent, the context of the "Send" span can be used as the creation context and no "Create" span needs to be created. |  |
| `settle` | One or more messages are settled. |  |
+---
+
`messaging.servicebus.disposition_status` 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.
| Value | Description | Stability |
@@ -240,12 +246,16 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`messaging.operation.type` 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.
| Value | Description | Stability |
diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md
index 2e490d9cfa..e372374e12 100644
--- a/docs/messaging/gcp-pubsub.md
+++ b/docs/messaging/gcp-pubsub.md
@@ -119,12 +119,16 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`messaging.operation.type` 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.
| Value | Description | Stability |
diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md
index 7164141dfe..cb45185042 100644
--- a/docs/messaging/kafka.md
+++ b/docs/messaging/kafka.md
@@ -128,12 +128,16 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`messaging.operation.type` 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.
| Value | Description | Stability |
diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md
index 72f1cf2eb1..3e26dcf624 100644
--- a/docs/messaging/messaging-metrics.md
+++ b/docs/messaging/messaging-metrics.md
@@ -122,12 +122,16 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi
**[10] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`messaging.operation.type` 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.
| Value | Description | Stability |
@@ -138,6 +142,8 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi
| `send` | One or more messages are provided for sending to an intermediary. If a single message is sent, the context of the "Send" span can be used as the creation context and no "Create" span needs to be created. |  |
| `settle` | One or more messages are settled. |  |
+---
+
`messaging.system` 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.
| Value | Description | Stability |
@@ -222,12 +228,16 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi
**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`messaging.system` 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.
| Value | Description | Stability |
@@ -319,12 +329,16 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi
**[9] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`messaging.system` 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.
| Value | Description | Stability |
@@ -419,12 +433,16 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi
**[9] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`messaging.system` 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.
| Value | Description | Stability |
diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md
index 2bdbcd1298..1b00dc2b3e 100644
--- a/docs/messaging/messaging-spans.md
+++ b/docs/messaging/messaging-spans.md
@@ -460,12 +460,16 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`messaging.operation.type` 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.
| Value | Description | Stability |
@@ -476,6 +480,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `send` | One or more messages are provided for sending to an intermediary. If a single message is sent, the context of the "Send" span can be used as the creation context and no "Create" span needs to be created. |  |
| `settle` | One or more messages are settled. |  |
+---
+
`messaging.system` 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.
| Value | Description | Stability |
diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md
index 440edc516b..2e00ee1954 100644
--- a/docs/messaging/rabbitmq.md
+++ b/docs/messaging/rabbitmq.md
@@ -111,12 +111,16 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`messaging.operation.type` 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.
| Value | Description | Stability |
diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md
index 8eeb14def1..e4380657af 100644
--- a/docs/messaging/rocketmq.md
+++ b/docs/messaging/rocketmq.md
@@ -123,12 +123,16 @@ and SHOULD be provided **at span creation time** (if provided at all):
* [`server.address`](/docs/attributes-registry/server.md)
* [`server.port`](/docs/attributes-registry/server.md)
+---
+
`error.type` 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.
| Value | Description | Stability |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+---
+
`messaging.operation.type` 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.
| Value | Description | Stability |
@@ -139,6 +143,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `send` | One or more messages are provided for sending to an intermediary. If a single message is sent, the context of the "Send" span can be used as the creation context and no "Create" span needs to be created. |  |
| `settle` | One or more messages are settled. |  |
+---
+
`messaging.rocketmq.consumption_model` 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.
| Value | Description | Stability |
@@ -146,6 +152,8 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `broadcasting` | Broadcasting consumption model |  |
| `clustering` | Clustering consumption model |  |
+---
+
`messaging.rocketmq.message.type` 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.
| Value | Description | Stability |
diff --git a/docs/object-stores/s3.md b/docs/object-stores/s3.md
index 4e5bec7952..67ce9cd98b 100644
--- a/docs/object-stores/s3.md
+++ b/docs/object-stores/s3.md
@@ -81,6 +81,8 @@ This applies in particular to the following operations:
**[8] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`rpc.system` 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.
| Value | Description | Stability |
diff --git a/docs/resource/README.md b/docs/resource/README.md
index 9e10b1f651..9f2f92f533 100644
--- a/docs/resource/README.md
+++ b/docs/resource/README.md
@@ -172,6 +172,8 @@ or another suitable identifier depending on the language.
The identifier `opentelemetry` is reserved and MUST NOT be used in this case.
All custom identifiers SHOULD be stable across different versions of an implementation.
+---
+
`telemetry.sdk.language` 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.
| Value | Description | Stability |
diff --git a/docs/resource/cloud-provider/aws/ecs.md b/docs/resource/cloud-provider/aws/ecs.md
index aacafb958f..c19219f8ec 100644
--- a/docs/resource/cloud-provider/aws/ecs.md
+++ b/docs/resource/cloud-provider/aws/ecs.md
@@ -24,6 +24,8 @@
| [`aws.ecs.task.family`](/docs/attributes-registry/aws.md) | string | The family name of the [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) used to create the ECS task. | `opentelemetry-family` | `Recommended` |  |
| [`aws.ecs.task.revision`](/docs/attributes-registry/aws.md) | string | The revision for the task definition used to create the ECS task. | `8`; `26` | `Recommended` |  |
+---
+
`aws.ecs.launchtype` 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.
| Value | Description | Stability |
diff --git a/docs/resource/cloud.md b/docs/resource/cloud.md
index bda2c91c75..0abfe90b1a 100644
--- a/docs/resource/cloud.md
+++ b/docs/resource/cloud.md
@@ -47,6 +47,8 @@ The following well-known definitions MUST be used if you set this attribute and
This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share
a TracerProvider.
+---
+
`cloud.platform` 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.
| Value | Description | Stability |
@@ -80,6 +82,8 @@ The following well-known definitions MUST be used if you set this attribute and
| `tencent_cloud_eks` | Tencent Cloud Elastic Kubernetes Service (EKS) |  |
| `tencent_cloud_scf` | Tencent Cloud Serverless Cloud Function (SCF) |  |
+---
+
`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.
| Value | Description | Stability |
diff --git a/docs/resource/host.md b/docs/resource/host.md
index 7b473376c1..d6618502df 100644
--- a/docs/resource/host.md
+++ b/docs/resource/host.md
@@ -59,6 +59,8 @@ privileged lookup of `host.id` is required, the value should be injected via the
**[3] `host.mac`:** MAC Addresses MUST be represented in [IEEE RA hexadecimal form](https://standards.ieee.org/wp-content/uploads/import/documents/tutorials/eui.pdf): as hyphen-separated octets in uppercase hexadecimal form from most to least significant.
+---
+
`host.arch` 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.
| Value | Description | Stability |
diff --git a/docs/resource/os.md b/docs/resource/os.md
index c815cd687e..70fa339386 100644
--- a/docs/resource/os.md
+++ b/docs/resource/os.md
@@ -32,6 +32,8 @@ In case of virtualized environments, this is the operating system as it is obser
| MacOS | `ProductBuildVersion` from `/System/Library/CoreServices/SystemVersion.plist` | `ProductBuildVersion` from `/System/Library/CoreServices/ServerVersion.plist` |
| Linux | `BUILD_ID` from `/etc/os-release` | `BUILD_ID` from `/usr/lib/os-release`;
contents of `/proc/sys/kernel/osrelease`|
+---
+
`os.type` 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.
| Value | Description | Stability |
diff --git a/docs/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md
index 16c1f09172..44ddac0d0c 100644
--- a/docs/rpc/connect-rpc.md
+++ b/docs/rpc/connect-rpc.md
@@ -35,6 +35,8 @@ Below is a table of attributes that SHOULD be included on client and server Conn
**[3] `rpc.connect_rpc.response.metadata`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
+---
+
`rpc.connect_rpc.error_code` 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.
| Value | Description | Stability |
diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md
index 043feed182..67c3b1b7ca 100644
--- a/docs/rpc/grpc.md
+++ b/docs/rpc/grpc.md
@@ -33,6 +33,8 @@ Below is a table of attributes that SHOULD be included on client and server gRPC
**[2] `rpc.grpc.response.metadata`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
+---
+
`rpc.grpc.status_code` 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.
| Value | Description | Stability |
diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md
index 17ecbc8359..058cba2920 100644
--- a/docs/rpc/rpc-metrics.md
+++ b/docs/rpc/rpc-metrics.md
@@ -349,6 +349,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+---
+
`network.transport` 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.
| Value | Description | Stability |
@@ -359,6 +361,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `udp` | UDP |  |
| `unix` | Unix domain socket |  |
+---
+
`network.type` 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.
| Value | Description | Stability |
@@ -366,6 +370,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `ipv4` | IPv4 |  |
| `ipv6` | IPv6 |  |
+---
+
`rpc.system` 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.
| Value | Description | Stability |
diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md
index 7ddf82cf4e..20928f293e 100644
--- a/docs/rpc/rpc-spans.md
+++ b/docs/rpc/rpc-spans.md
@@ -132,6 +132,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
**[7] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`network.transport` 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.
| Value | Description | Stability |
@@ -142,6 +144,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `udp` | UDP |  |
| `unix` | Unix domain socket |  |
+---
+
`network.type` 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.
| Value | Description | Stability |
@@ -149,6 +153,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `ipv4` | IPv4 |  |
| `ipv6` | IPv6 |  |
+---
+
`rpc.system` 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.
| Value | Description | Stability |
@@ -209,6 +215,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
**[9] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+---
+
`network.transport` 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.
| Value | Description | Stability |
@@ -219,6 +227,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `udp` | UDP |  |
| `unix` | Unix domain socket |  |
+---
+
`network.type` 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.
| Value | Description | Stability |
@@ -226,6 +236,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `ipv4` | IPv4 |  |
| `ipv6` | IPv6 |  |
+---
+
`rpc.system` 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.
| Value | Description | Stability |
@@ -269,6 +281,8 @@ In the lifetime of an RPC stream, an event for each message sent/received on cli
**[1] `rpc.message.id`:** This way we guarantee that the values will be consistent between different implementations.
+---
+
`rpc.message.type` 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.
| Value | Description | Stability |
diff --git a/docs/runtime/dotnet-metrics.md b/docs/runtime/dotnet-metrics.md
index a8bc36f8d8..00b0b40035 100644
--- a/docs/runtime/dotnet-metrics.md
+++ b/docs/runtime/dotnet-metrics.md
@@ -92,6 +92,8 @@ This metric reports the same values as accessing the corresponding processor tim
|---|---|---|---|---|---|
| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The mode of the CPU | `user`; `system` | `Required` |  |
+---
+
`cpu.mode` 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.
| Value | Description | Stability |
@@ -161,6 +163,8 @@ This metric uses the [`GC.CollectionCount(int generation)`](https://learn.micros
|---|---|---|---|---|---|
| [`dotnet.gc.heap.generation`](/docs/attributes-registry/dotnet.md) | string | Name of the garbage collector managed heap generation. | `gen0`; `gen1`; `gen2` | `Required` |  |
+---
+
`dotnet.gc.heap.generation` 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.
| Value | Description | Stability |
@@ -244,6 +248,8 @@ This metric reports the same values as calling [`GC.GetGCMemoryInfo().Generation
|---|---|---|---|---|---|
| [`dotnet.gc.heap.generation`](/docs/attributes-registry/dotnet.md) | string | Name of the garbage collector managed heap generation. | `gen0`; `gen1`; `gen2` | `Required` |  |
+---
+
`dotnet.gc.heap.generation` 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.
| Value | Description | Stability |
@@ -281,6 +287,8 @@ This metric reports the same values as calling [`GC.GetGCMemoryInfo().Generation
|---|---|---|---|---|---|
| [`dotnet.gc.heap.generation`](/docs/attributes-registry/dotnet.md) | string | Name of the garbage collector managed heap generation. | `gen0`; `gen1`; `gen2` | `Required` |  |
+---
+
`dotnet.gc.heap.generation` 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.
| Value | Description | Stability |
@@ -566,6 +574,8 @@ This metric reports the same values as counting calls to [`AppDomain.CurrentDoma
|---|---|---|---|---|---|
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. | `System.OperationCanceledException`; `Contoso.MyException` | `Required` |  |
+---
+
`error.type` 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.
| Value | Description | Stability |
diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md
index 6391e16bc4..7a18c87fd2 100644
--- a/docs/runtime/go-metrics.md
+++ b/docs/runtime/go-metrics.md
@@ -56,6 +56,8 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`go.memory.type`](/docs/attributes-registry/go.md) | string | The type of memory. | `other`; `stack` | `Recommended` |  |
+---
+
`go.memory.type` 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.
| Value | Description | Stability |
diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md
index 57e28e749a..9ef4d1bade 100644
--- a/docs/runtime/jvm-metrics.md
+++ b/docs/runtime/jvm-metrics.md
@@ -68,6 +68,8 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle
**[1] `jvm.memory.pool.name`:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
+---
+
`jvm.memory.type` 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.
| Value | Description | Stability |
@@ -103,6 +105,8 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle
**[1] `jvm.memory.pool.name`:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
+---
+
`jvm.memory.type` 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.
| Value | Description | Stability |
@@ -138,6 +142,8 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle
**[1] `jvm.memory.pool.name`:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
+---
+
`jvm.memory.type` 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.
| Value | Description | Stability |
@@ -173,6 +179,8 @@ This metric is obtained from [`MemoryPoolMXBean#getCollectionUsage()`](https://d
**[1] `jvm.memory.pool.name`:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
+---
+
`jvm.memory.type` 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.
| Value | Description | Stability |
@@ -260,6 +268,8 @@ Note that this is the number of platform threads (as opposed to virtual threads)
| [`jvm.thread.daemon`](/docs/attributes-registry/jvm.md) | boolean | Whether the thread is daemon or not. | | `Recommended` |  |
| [`jvm.thread.state`](/docs/attributes-registry/jvm.md) | string | State of the thread. | `runnable`; `blocked` | `Recommended` |  |
+---
+
`jvm.thread.state` 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.
| Value | Description | Stability |
@@ -450,6 +460,8 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle
**[1] `jvm.memory.pool.name`:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).
+---
+
`jvm.memory.type` 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.
| Value | Description | Stability |
diff --git a/docs/runtime/nodejs-metrics.md b/docs/runtime/nodejs-metrics.md
index d44fa3a1ea..86754eb5db 100644
--- a/docs/runtime/nodejs-metrics.md
+++ b/docs/runtime/nodejs-metrics.md
@@ -232,6 +232,8 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`nodejs.eventloop.state`](/docs/attributes-registry/nodejs.md) | string | The state of event loop time. | `active`; `idle` | `Required` |  |
+---
+
`nodejs.eventloop.state` 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.
| Value | Description | Stability |
diff --git a/docs/runtime/v8js-metrics.md b/docs/runtime/v8js-metrics.md
index 6d00bb9c64..83be405a9e 100644
--- a/docs/runtime/v8js-metrics.md
+++ b/docs/runtime/v8js-metrics.md
@@ -52,6 +52,8 @@ of `[ 0.01, 0.1, 1, 10 ]`.
|---|---|---|---|---|---|
| [`v8js.gc.type`](/docs/attributes-registry/v8js.md) | string | The type of garbage collection. | `major`; `minor`; `incremental` | `Required` |  |
+---
+
`v8js.gc.type` 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.
| Value | Description | Stability |
@@ -89,6 +91,8 @@ This metric is [recommended][MetricRecommended].
**[1] `v8js.heap.space.name`:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics)
+---
+
`v8js.heap.space.name` 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.
| Value | Description | Stability |
@@ -127,6 +131,8 @@ This metric is [recommended][MetricRecommended].
**[1] `v8js.heap.space.name`:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics)
+---
+
`v8js.heap.space.name` 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.
| Value | Description | Stability |
@@ -165,6 +171,8 @@ This metric is [recommended][MetricRecommended].
**[1] `v8js.heap.space.name`:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics)
+---
+
`v8js.heap.space.name` 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.
| Value | Description | Stability |
@@ -203,6 +211,8 @@ This metric is [recommended][MetricRecommended].
**[1] `v8js.heap.space.name`:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics)
+---
+
`v8js.heap.space.name` 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.
| Value | Description | Stability |
diff --git a/docs/system/container-metrics.md b/docs/system/container-metrics.md
index 69af1b7525..8d7faa892c 100644
--- a/docs/system/container-metrics.md
+++ b/docs/system/container-metrics.md
@@ -37,6 +37,8 @@ This metric is [opt-in][MetricOptIn].
**[2] `cpu.mode`:** Required if mode is available, i.e. metrics coming from the Docker Stats API.
+---
+
`cpu.mode` 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.
| Value | Description | Stability |
@@ -80,6 +82,8 @@ This metric is [opt-in][MetricOptIn].
**[2] `cpu.mode`:** Required if mode is available, i.e. metrics coming from the Docker Stats API.
+---
+
`cpu.mode` 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.
| Value | Description | Stability |
@@ -142,6 +146,8 @@ This metric is [opt-in][MetricOptIn].
| [`disk.io.direction`](/docs/attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | `Recommended` |  |
| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` |  |
+---
+
`disk.io.direction` 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.
| Value | Description | Stability |
@@ -176,6 +182,8 @@ This metric is [opt-in][MetricOptIn].
| [`network.interface.name`](/docs/attributes-registry/network.md) | string | The network interface name. | `lo`; `eth0` | `Recommended` |  |
| [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` |  |
+---
+
`network.io.direction` 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.
| Value | Description | Stability |
diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md
index 6767584e55..749f542b2c 100644
--- a/docs/system/process-metrics.md
+++ b/docs/system/process-metrics.md
@@ -67,6 +67,8 @@ This metric is [recommended][MetricRecommended].
**[1] `cpu.mode`:** Following states SHOULD be used: `user`, `system`, `wait`
+---
+
`cpu.mode` 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.
| Value | Description | Stability |
@@ -106,6 +108,8 @@ This metric is [opt-in][MetricOptIn].
**[1] `cpu.mode`:** Following states SHOULD be used: `user`, `system`, `wait`
+---
+
`cpu.mode` 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.
| Value | Description | Stability |
@@ -183,6 +187,8 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`disk.io.direction`](/docs/attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | `Recommended` |  |
+---
+
`disk.io.direction` 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.
| Value | Description | Stability |
@@ -214,6 +220,8 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` |  |
+---
+
`network.io.direction` 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.
| Value | Description | Stability |
@@ -285,6 +293,8 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`process.context_switch_type`](/docs/attributes-registry/process.md) | string | Specifies whether the context switches for this data point were voluntary or involuntary. | `voluntary`; `involuntary` | `Recommended` |  |
+---
+
`process.context_switch_type` 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.
| Value | Description | Stability |
@@ -316,6 +326,8 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`process.paging.fault_type`](/docs/attributes-registry/process.md) | string | The type of page fault for this data point. Type `major` is for major/hard page faults, and `minor` is for minor/soft page faults. | `major`; `minor` | `Recommended` |  |
+---
+
`process.paging.fault_type` 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.
| Value | Description | Stability |
diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md
index 0ec0a5894c..61b65cd13c 100644
--- a/docs/system/system-metrics.md
+++ b/docs/system/system-metrics.md
@@ -126,6 +126,8 @@ This metric is [recommended][MetricRecommended].
**[1] `cpu.mode`:** Following states SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`
+---
+
`cpu.mode` 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.
| Value | Description | Stability |
@@ -166,6 +168,8 @@ This metric is [opt-in][MetricOptIn].
**[1] `cpu.mode`:** Following modes SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`
+---
+
`cpu.mode` 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.
| Value | Description | Stability |
@@ -275,6 +279,8 @@ available on the system, that is `system.memory.limit`.
|---|---|---|---|---|---|
| [`system.memory.state`](/docs/attributes-registry/system.md) | string | The memory state | `free`; `cached` | `Recommended` |  |
+---
+
`system.memory.state` 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.
| Value | Description | Stability |
@@ -353,6 +359,8 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`system.memory.state`](/docs/attributes-registry/system.md) | string | The memory state | `free`; `cached` | `Recommended` |  |
+---
+
`system.memory.state` 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.
| Value | Description | Stability |
@@ -391,6 +399,8 @@ This metric is [recommended][MetricRecommended].
| [`system.device`](/docs/attributes-registry/system.md) | string | Unique identifier for the device responsible for managing paging operations. | `/dev/dm-0` | `Recommended` |  |
| [`system.paging.state`](/docs/attributes-registry/system.md) | string | The memory paging state | `free` | `Recommended` |  |
+---
+
`system.paging.state` 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.
| Value | Description | Stability |
@@ -423,6 +433,8 @@ This metric is [recommended][MetricRecommended].
| [`system.device`](/docs/attributes-registry/system.md) | string | Unique identifier for the device responsible for managing paging operations. | `/dev/dm-0` | `Recommended` |  |
| [`system.paging.state`](/docs/attributes-registry/system.md) | string | The memory paging state | `free` | `Recommended` |  |
+---
+
`system.paging.state` 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.
| Value | Description | Stability |
@@ -454,6 +466,8 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`system.paging.type`](/docs/attributes-registry/system.md) | string | The memory paging type | `minor` | `Recommended` |  |
+---
+
`system.paging.type` 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.
| Value | Description | Stability |
@@ -486,6 +500,8 @@ This metric is [recommended][MetricRecommended].
| [`system.paging.direction`](/docs/attributes-registry/system.md) | string | The paging access direction | `in` | `Recommended` |  |
| [`system.paging.type`](/docs/attributes-registry/system.md) | string | The memory paging type | `minor` | `Recommended` |  |
+---
+
`system.paging.direction` 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.
| Value | Description | Stability |
@@ -493,6 +509,8 @@ This metric is [recommended][MetricRecommended].
| `in` | in |  |
| `out` | out |  |
+---
+
`system.paging.type` 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.
| Value | Description | Stability |
@@ -529,6 +547,8 @@ This metric is [recommended][MetricRecommended].
| [`disk.io.direction`](/docs/attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | `Recommended` |  |
| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` |  |
+---
+
`disk.io.direction` 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.
| Value | Description | Stability |
@@ -561,6 +581,8 @@ This metric is [recommended][MetricRecommended].
| [`disk.io.direction`](/docs/attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | `Recommended` |  |
| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` |  |
+---
+
`disk.io.direction` 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.
| Value | Description | Stability |
@@ -629,6 +651,8 @@ This metric is [recommended][MetricRecommended].
| [`disk.io.direction`](/docs/attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | `Recommended` |  |
| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` |  |
+---
+
`disk.io.direction` 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.
| Value | Description | Stability |
@@ -661,6 +685,8 @@ This metric is [recommended][MetricRecommended].
| [`disk.io.direction`](/docs/attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | `Recommended` |  |
| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` |  |
+---
+
`disk.io.direction` 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.
| Value | Description | Stability |
@@ -727,6 +753,8 @@ SHOULD equal the total storage capacity of the filesystem, that is `system.files
| [`system.filesystem.state`](/docs/attributes-registry/system.md) | string | The filesystem state | `used` | `Recommended` |  |
| [`system.filesystem.type`](/docs/attributes-registry/system.md) | string | The filesystem type | `ext4` | `Recommended` |  |
+---
+
`system.filesystem.state` 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.
| Value | Description | Stability |
@@ -735,6 +763,8 @@ SHOULD equal the total storage capacity of the filesystem, that is `system.files
| `reserved` | reserved |  |
| `used` | used |  |
+---
+
`system.filesystem.type` 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.
| Value | Description | Stability |
@@ -774,6 +804,8 @@ This metric is [recommended][MetricRecommended].
| [`system.filesystem.state`](/docs/attributes-registry/system.md) | string | The filesystem state | `used` | `Recommended` |  |
| [`system.filesystem.type`](/docs/attributes-registry/system.md) | string | The filesystem type | `ext4` | `Recommended` |  |
+---
+
`system.filesystem.state` 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.
| Value | Description | Stability |
@@ -782,6 +814,8 @@ This metric is [recommended][MetricRecommended].
| `reserved` | reserved |  |
| `used` | used |  |
+---
+
`system.filesystem.type` 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.
| Value | Description | Stability |
@@ -820,6 +854,8 @@ This metric is [opt-in][MetricOptIn].
| [`system.filesystem.mountpoint`](/docs/attributes-registry/system.md) | string | The filesystem mount path | `/mnt/data` | `Recommended` |  |
| [`system.filesystem.type`](/docs/attributes-registry/system.md) | string | The filesystem type | `ext4` | `Recommended` |  |
+---
+
`system.filesystem.type` 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.
| Value | Description | Stability |
@@ -866,6 +902,8 @@ This metric is [recommended][MetricRecommended].
| [`network.interface.name`](/docs/attributes-registry/network.md) | string | The network interface name. | `lo`; `eth0` | `Recommended` |  |
| [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` |  |
+---
+
`network.io.direction` 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.
| Value | Description | Stability |
@@ -898,6 +936,8 @@ This metric is [recommended][MetricRecommended].
| [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` |  |
| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` |  |
+---
+
`network.io.direction` 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.
| Value | Description | Stability |
@@ -936,6 +976,8 @@ This metric is [recommended][MetricRecommended].
| [`network.interface.name`](/docs/attributes-registry/network.md) | string | The network interface name. | `lo`; `eth0` | `Recommended` |  |
| [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` |  |
+---
+
`network.io.direction` 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.
| Value | Description | Stability |
@@ -968,6 +1010,8 @@ This metric is [recommended][MetricRecommended].
| [`network.interface.name`](/docs/attributes-registry/network.md) | string | The network interface name. | `lo`; `eth0` | `Recommended` |  |
| [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` |  |
+---
+
`network.io.direction` 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.
| Value | Description | Stability |
@@ -1007,6 +1051,8 @@ Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport. For example
different processes could be listening on TCP port 12345 and UDP port 12345.
+---
+
`network.transport` 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.
| Value | Description | Stability |
@@ -1017,6 +1063,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| `udp` | UDP |  |
| `unix` | Unix domain socket |  |
+---
+
`system.network.state` 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.
| Value | Description | Stability |
@@ -1062,6 +1110,8 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`system.process.status`](/docs/attributes-registry/system.md) | string | The process state, e.g., [Linux Process State Codes](https://man7.org/linux/man-pages/man1/ps.1.html#PROCESS_STATE_CODES) | `running` | `Recommended` |  |
+---
+
`system.process.status` 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.
| Value | Description | Stability |
@@ -1175,6 +1225,8 @@ See also the [Slab allocator](https://blogs.oracle.com/linux/post/understanding-
|---|---|---|---|---|---|
| [`linux.memory.slab.state`](/docs/attributes-registry/linux.md) | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | `Recommended` |  |
+---
+
`linux.memory.slab.state` 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.
| Value | Description | Stability |
diff --git a/templates/registry/markdown/enum_macros.j2 b/templates/registry/markdown/enum_macros.j2
index 45f67e0a5e..8dbc583cdc 100644
--- a/templates/registry/markdown/enum_macros.j2
+++ b/templates/registry/markdown/enum_macros.j2
@@ -1,6 +1,8 @@
{% import 'stability.j2' as stability %}
{% macro filter(member) %}{% if snippet_type is not defined or (member.deprecated is none or member.deprecated == "") %}{{ "True" }}{% else %}{{ "False" }}{% endif %}{% endmacro %}
{% macro table(enum, notes) %}
+---
+
`{{enum.name}}` 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.
| Value | Description | Stability |
From 5517079850f4a1bedfbb376354e2a2dfe74edc86 Mon Sep 17 00:00:00 2001
From: Christos Markou
Date: Thu, 21 Nov 2024 11:20:33 +0200
Subject: [PATCH 08/32] Add k8s.{pod,node}.network.{io,errors} metrics (#1427)
Signed-off-by: ChrsMark
Co-authored-by: Liudmila Molkova
---
.chloggen/add_k8s_network_metrics.yaml | 22 ++++
docs/system/k8s-metrics.md | 136 +++++++++++++++++++++++++
model/k8s/metrics.yaml | 44 ++++++++
3 files changed, 202 insertions(+)
create mode 100755 .chloggen/add_k8s_network_metrics.yaml
diff --git a/.chloggen/add_k8s_network_metrics.yaml b/.chloggen/add_k8s_network_metrics.yaml
new file mode 100755
index 0000000000..979248f208
--- /dev/null
+++ b/.chloggen/add_k8s_network_metrics.yaml
@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: k8s
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add k8s.{node,pod}.network.{io,errors} metrics
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1427]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/docs/system/k8s-metrics.md b/docs/system/k8s-metrics.md
index bbadff485d..a94eac4050 100644
--- a/docs/system/k8s-metrics.md
+++ b/docs/system/k8s-metrics.md
@@ -81,6 +81,74 @@ This metric is [recommended][MetricRecommended].
+### Metric: `k8s.pod.network.io`
+
+This metric is [recommended][MetricRecommended].
+
+
+
+
+
+
+
+
+| Name | Instrument Type | Unit (UCUM) | Description | Stability |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `k8s.pod.network.io` | Counter | `By` | Network bytes for the Pod |  |
+
+| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`network.interface.name`](/docs/attributes-registry/network.md) | string | The network interface name. | `lo`; `eth0` | `Recommended` |  |
+| [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` |  |
+
+---
+
+`network.io.direction` 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.
+
+| Value | Description | Stability |
+|---|---|---|
+| `receive` | receive |  |
+| `transmit` | transmit |  |
+
+
+
+
+
+
+### Metric: `k8s.pod.network.errors`
+
+This metric is [recommended][MetricRecommended].
+
+
+
+
+
+
+
+
+| Name | Instrument Type | Unit (UCUM) | Description | Stability |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `k8s.pod.network.errors` | Counter | `{error}` | Pod network errors |  |
+
+| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`network.interface.name`](/docs/attributes-registry/network.md) | string | The network interface name. | `lo`; `eth0` | `Recommended` |  |
+| [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` |  |
+
+---
+
+`network.io.direction` 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.
+
+| Value | Description | Stability |
+|---|---|---|
+| `receive` | receive |  |
+| `transmit` | transmit |  |
+
+
+
+
+
+
### Metric: `k8s.node.cpu.time`
This metric is [recommended][MetricRecommended].
@@ -147,5 +215,73 @@ This metric is [recommended][MetricRecommended].
+### Metric: `k8s.node.network.io`
+
+This metric is [recommended][MetricRecommended].
+
+
+
+
+
+
+
+
+| Name | Instrument Type | Unit (UCUM) | Description | Stability |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `k8s.node.network.io` | Counter | `By` | Network bytes for the Node |  |
+
+| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`network.interface.name`](/docs/attributes-registry/network.md) | string | The network interface name. | `lo`; `eth0` | `Recommended` |  |
+| [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` |  |
+
+---
+
+`network.io.direction` 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.
+
+| Value | Description | Stability |
+|---|---|---|
+| `receive` | receive |  |
+| `transmit` | transmit |  |
+
+
+
+
+
+
+### Metric: `k8s.node.network.errors`
+
+This metric is [recommended][MetricRecommended].
+
+
+
+
+
+
+
+
+| Name | Instrument Type | Unit (UCUM) | Description | Stability |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `k8s.node.network.errors` | Counter | `{error}` | Node network errors |  |
+
+| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`network.interface.name`](/docs/attributes-registry/network.md) | string | The network interface name. | `lo`; `eth0` | `Recommended` |  |
+| [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` |  |
+
+---
+
+`network.io.direction` 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.
+
+| Value | Description | Stability |
+|---|---|---|
+| `receive` | receive |  |
+| `transmit` | transmit |  |
+
+
+
+
+
+
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
diff --git a/model/k8s/metrics.yaml b/model/k8s/metrics.yaml
index a09cfee780..2e59cef71e 100644
--- a/model/k8s/metrics.yaml
+++ b/model/k8s/metrics.yaml
@@ -30,6 +30,28 @@ groups:
instrument: gauge
unit: "By"
+ # k8s.pod.network.* metrics
+ - id: metric.k8s.pod.network.io
+ type: metric
+ metric_name: k8s.pod.network.io
+ stability: experimental
+ brief: "Network bytes for the Pod"
+ instrument: counter
+ unit: "By"
+ attributes:
+ - ref: network.interface.name
+ - ref: network.io.direction
+ - id: metric.k8s.pod.network.errors
+ type: metric
+ metric_name: k8s.pod.network.errors
+ stability: experimental
+ brief: "Pod network errors"
+ instrument: counter
+ unit: "{error}"
+ attributes:
+ - ref: network.interface.name
+ - ref: network.io.direction
+
# k8s.node.cpu.* metrics
- id: metric.k8s.node.cpu.time
type: metric
@@ -60,3 +82,25 @@ groups:
Total memory usage of the Node
instrument: gauge
unit: "By"
+
+ # k8s.node.network.* metrics
+ - id: metric.k8s.node.network.io
+ type: metric
+ metric_name: k8s.node.network.io
+ stability: experimental
+ brief: "Network bytes for the Node"
+ instrument: counter
+ unit: "By"
+ attributes:
+ - ref: network.interface.name
+ - ref: network.io.direction
+ - id: metric.k8s.node.network.errors
+ type: metric
+ metric_name: k8s.node.network.errors
+ stability: experimental
+ brief: "Node network errors"
+ instrument: counter
+ unit: "{error}"
+ attributes:
+ - ref: network.interface.name
+ - ref: network.io.direction
From c28e251db4679c45fed56490f21395773ab83028 Mon Sep 17 00:00:00 2001
From: Jackson Weber <47067795+JacksonWeber@users.noreply.github.com>
Date: Fri, 22 Nov 2024 11:10:25 -0800
Subject: [PATCH 09/32] add `http.request.synthetic` attribute to server spans
and metrics (#1523)
Co-authored-by: Trask Stalnaker
Co-authored-by: Liudmila Molkova
---
.chloggen/add-synthetic-source.yaml | 22 ++++++++++++++++
docs/attributes-registry/user-agent.md | 16 ++++++++++--
docs/http/http-metrics.md | 36 ++++++++++++++++++++++++++
docs/http/http-spans.md | 24 +++++++++++++++++
model/http/metrics.yaml | 2 ++
model/http/spans.yaml | 4 +++
model/user-agent/registry.yaml | 19 ++++++++++++++
7 files changed, 121 insertions(+), 2 deletions(-)
create mode 100644 .chloggen/add-synthetic-source.yaml
diff --git a/.chloggen/add-synthetic-source.yaml b/.chloggen/add-synthetic-source.yaml
new file mode 100644
index 0000000000..935eb5529e
--- /dev/null
+++ b/.chloggen/add-synthetic-source.yaml
@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: user_agent
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add the `user_agent.synthetic.type` attribute to specify the category of synthetic traffic, such as tests or bots.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1127]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md
index 37be97223f..3952005cd9 100644
--- a/docs/attributes-registry/user-agent.md
+++ b/docs/attributes-registry/user-agent.md
@@ -14,8 +14,20 @@ Describes user-agent attributes.
|---|---|---|---|---|
| `user_agent.name` | string | Name of the user-agent extracted from original. Usually refers to the browser's name. [1] | `Safari`; `YourApp` |  |
| `user_agent.original` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1`; `YourApp/1.0.0 grpc-java-okhttp/1.27.2` |  |
-| `user_agent.version` | string | Version of the user-agent extracted from original. Usually refers to the browser's version [2] | `14.1.2`; `1.0.0` |  |
+| `user_agent.synthetic.type` | string | Specifies the category of synthetic traffic, such as tests or bots. [2] | `bot`; `test` |  |
+| `user_agent.version` | string | Version of the user-agent extracted from original. Usually refers to the browser's version [3] | `14.1.2`; `1.0.0` |  |
**[1] `user_agent.name`:** [Example](https://www.whatsmyua.info) of extracting browser's name from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant name SHOULD be selected. In such a scenario it should align with `user_agent.version`
-**[2] `user_agent.version`:** [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant version SHOULD be selected. In such a scenario it should align with `user_agent.name`
+**[2] `user_agent.synthetic.type`:** This attribute MAY be derived from the contents of the `user_agent.original` attribute. Components that populate the attribute are responsible for determining what they consider to be synthetic bot or test traffic. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests.
+
+**[3] `user_agent.version`:** [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant version SHOULD be selected. In such a scenario it should align with `user_agent.name`
+
+---
+
+`user_agent.synthetic.type` 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.
+
+| Value | Description | Stability |
+|---|---|---|
+| `bot` | Bot source. |  |
+| `test` | Synthetic test source. |  |
diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md
index 60020b3a9d..a5136e6d5e 100644
--- a/docs/http/http-metrics.md
+++ b/docs/http/http-metrics.md
@@ -89,6 +89,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` |  |
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` |  |
+| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as tests or bots. [10] | `bot`; `test` | `Opt-In` |  |
**[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
@@ -143,6 +144,8 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
> Since this attribute is based on HTTP headers, opting in to it may allow an attacker
> to trigger cardinality limits, degrading the usefulness of the metric.
+**[10] `user_agent.synthetic.type`:** This attribute MAY be derived from the contents of the `user_agent.original` attribute. Components that populate the attribute are responsible for determining what they consider to be synthetic bot or test traffic. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests.
+
---
`error.type` 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.
@@ -168,6 +171,15 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
| `PUT` | PUT method. |  |
| `TRACE` | TRACE method. |  |
+---
+
+`user_agent.synthetic.type` 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.
+
+| Value | Description | Stability |
+|---|---|---|
+| `bot` | Bot source. |  |
+| `test` | Synthetic test source. |  |
+
@@ -270,6 +282,7 @@ This metric is optional.
| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` |  |
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` |  |
+| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as tests or bots. [10] | `bot`; `test` | `Opt-In` |  |
**[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
@@ -324,6 +337,8 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
> Since this attribute is based on HTTP headers, opting in to it may allow an attacker
> to trigger cardinality limits, degrading the usefulness of the metric.
+**[10] `user_agent.synthetic.type`:** This attribute MAY be derived from the contents of the `user_agent.original` attribute. Components that populate the attribute are responsible for determining what they consider to be synthetic bot or test traffic. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests.
+
---
`error.type` 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.
@@ -349,6 +364,15 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
| `PUT` | PUT method. |  |
| `TRACE` | TRACE method. |  |
+---
+
+`user_agent.synthetic.type` 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.
+
+| Value | Description | Stability |
+|---|---|---|
+| `bot` | Bot source. |  |
+| `test` | Synthetic test source. |  |
+
@@ -382,6 +406,7 @@ This metric is optional.
| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` |  |
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` |  |
+| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as tests or bots. [10] | `bot`; `test` | `Opt-In` |  |
**[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
@@ -436,6 +461,8 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
> Since this attribute is based on HTTP headers, opting in to it may allow an attacker
> to trigger cardinality limits, degrading the usefulness of the metric.
+**[10] `user_agent.synthetic.type`:** This attribute MAY be derived from the contents of the `user_agent.original` attribute. Components that populate the attribute are responsible for determining what they consider to be synthetic bot or test traffic. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests.
+
---
`error.type` 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.
@@ -461,6 +488,15 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
| `PUT` | PUT method. |  |
| `TRACE` | TRACE method. |  |
+---
+
+`user_agent.synthetic.type` 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.
+
+| Value | Description | Stability |
+|---|---|---|
+| `bot` | Bot source. |  |
+| `test` | Synthetic test source. |  |
+
diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md
index 045a69a408..37781049ea 100644
--- a/docs/http/http-spans.md
+++ b/docs/http/http-spans.md
@@ -162,6 +162,7 @@ For an HTTP client span, `SpanKind` MUST be `CLIENT`.
| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | `Opt-In` |  |
| [`url.template`](/docs/attributes-registry/url.md) | string | The low-cardinality template of an [absolute path reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.2). [14] | `/users/{id}`; `/users/:id`; `/users?id={id}` | `Opt-In` |  |
| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1`; `YourApp/1.0.0 grpc-java-okhttp/1.27.2` | `Opt-In` |  |
+| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as tests or bots. [15] | `bot`; `test` | `Opt-In` |  |
**[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
@@ -245,6 +246,8 @@ The attribute value MUST consist of either multiple header values as an array of
**[14] `url.template`:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation.
+**[15] `user_agent.synthetic.type`:** This attribute MAY be derived from the contents of the `user_agent.original` attribute. Components that populate the attribute are responsible for determining what they consider to be synthetic bot or test traffic. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests.
+
The following attributes can be important for making sampling decisions
and SHOULD be provided **at span creation time** (if provided at all):
@@ -290,6 +293,15 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `udp` | UDP |  |
| `unix` | Unix domain socket |  |
+---
+
+`user_agent.synthetic.type` 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.
+
+| Value | Description | Stability |
+|---|---|---|
+| `bot` | Bot source. |  |
+| `test` | Synthetic test source. |  |
+
@@ -410,6 +422,7 @@ For an HTTP server span, `SpanKind` MUST be `SERVER`.
| [`network.local.address`](/docs/attributes-registry/network.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.1.2.80`; `/tmp/my.sock` | `Opt-In` |  |
| [`network.local.port`](/docs/attributes-registry/network.md) | int | Local socket port. Useful in case of a multi-port host. | `65123` | `Opt-In` |  |
| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [17] | `tcp`; `udp` | `Opt-In` |  |
+| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as tests or bots. [18] | `bot`; `test` | `Opt-In` |  |
**[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
@@ -491,6 +504,8 @@ The attribute value MUST consist of either multiple header values as an array of
**[17] `network.transport`:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible.
+**[18] `user_agent.synthetic.type`:** This attribute MAY be derived from the contents of the `user_agent.original` attribute. Components that populate the attribute are responsible for determining what they consider to be synthetic bot or test traffic. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests.
+
The following attributes can be important for making sampling decisions
and SHOULD be provided **at span creation time** (if provided at all):
@@ -541,6 +556,15 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `udp` | UDP |  |
| `unix` | Unix domain socket |  |
+---
+
+`user_agent.synthetic.type` 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.
+
+| Value | Description | Stability |
+|---|---|---|
+| `bot` | Bot source. |  |
+| `test` | Synthetic test source. |  |
+
diff --git a/model/http/metrics.yaml b/model/http/metrics.yaml
index 78283fdf75..90f74a7656 100644
--- a/model/http/metrics.yaml
+++ b/model/http/metrics.yaml
@@ -18,6 +18,8 @@ groups:
> **Warning**
> Since this attribute is based on HTTP headers, opting in to it may allow an attacker
> to trigger cardinality limits, degrading the usefulness of the metric.
+ - ref: user_agent.synthetic.type
+ requirement_level: opt_in
- id: metric_attributes.http.client
type: attribute_group
brief: 'HTTP client attributes'
diff --git a/model/http/spans.yaml b/model/http/spans.yaml
index 2698415ce3..86ee3154c4 100644
--- a/model/http/spans.yaml
+++ b/model/http/spans.yaml
@@ -45,6 +45,8 @@ groups:
requirement_level: opt_in
- ref: http.response.body.size
requirement_level: opt_in
+ - ref: user_agent.synthetic.type
+ requirement_level: opt_in
- id: span.http.server
type: span
@@ -113,3 +115,5 @@ groups:
requirement_level: opt_in
- ref: http.response.body.size
requirement_level: opt_in
+ - ref: user_agent.synthetic.type
+ requirement_level: opt_in
diff --git a/model/user-agent/registry.yaml b/model/user-agent/registry.yaml
index 2b856ecdf5..369aad35cd 100644
--- a/model/user-agent/registry.yaml
+++ b/model/user-agent/registry.yaml
@@ -35,3 +35,22 @@ groups:
using a user-agent for non-browser products, such as microservices with multiple names/versions inside the
`user_agent.original`, the most significant version SHOULD be selected. In such a scenario it should align
with `user_agent.name`
+ - id: user_agent.synthetic.type
+ stability: experimental
+ brief: >
+ Specifies the category of synthetic traffic, such as tests or bots.
+ note: >
+ This attribute MAY be derived from the contents of the `user_agent.original` attribute.
+ Components that populate the attribute are responsible for determining what they consider to be synthetic bot or test traffic.
+ This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result
+ of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests.
+ type:
+ members:
+ - id: bot
+ value: "bot"
+ brief: 'Bot source.'
+ stability: experimental
+ - id: test
+ value: "test"
+ brief: 'Synthetic test source.'
+ stability: experimental
From 03e1ba08fe6be7285983e21db5e098a3d6ea3ac4 Mon Sep 17 00:00:00 2001
From: Liudmila Molkova
Date: Mon, 25 Nov 2024 08:08:46 -0800
Subject: [PATCH 10/32] Remove requirement_level usages from registry and add a
policy to check (#1606)
---
model/aspnetcore/metrics.yaml | 2 ++
model/aspnetcore/registry.yaml | 3 ---
model/aws/registry.yaml | 2 --
model/go/registry.yaml | 1 -
model/process/registry.yaml | 2 --
model/telemetry/registry.yaml | 3 ---
policies/registry.rego | 14 ++++++++++++++
policies_test/registry_test.rego | 6 ++++++
8 files changed, 22 insertions(+), 11 deletions(-)
diff --git a/model/aspnetcore/metrics.yaml b/model/aspnetcore/metrics.yaml
index fd0c2c4d78..89951e26d7 100644
--- a/model/aspnetcore/metrics.yaml
+++ b/model/aspnetcore/metrics.yaml
@@ -43,6 +43,8 @@ groups:
examples: ['System.OperationCanceledException', 'Contoso.MyException']
requirement_level: required
- ref: aspnetcore.diagnostics.handler.type
+ requirement_level:
+ conditionally_required: if and only if the exception was handled by this handler.
- ref: aspnetcore.diagnostics.exception.result
requirement_level: required
diff --git a/model/aspnetcore/registry.yaml b/model/aspnetcore/registry.yaml
index 16a28a5535..71677d5980 100644
--- a/model/aspnetcore/registry.yaml
+++ b/model/aspnetcore/registry.yaml
@@ -31,7 +31,6 @@ groups:
stability: stable
brief: Rate-limiting result, shows whether the lease was acquired or contains a rejection reason
examples: ["acquired", "request_canceled"]
- requirement_level: required
- id: aspnetcore.routing.is_fallback
type: boolean
stability: stable
@@ -43,8 +42,6 @@ groups:
brief: Full type name of the [`IExceptionHandler`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.diagnostics.iexceptionhandler)
implementation that handled the exception.
examples: ["Contoso.MyHandler"]
- requirement_level:
- conditionally_required: if and only if the exception was handled by this handler.
- id: aspnetcore.request.is_unhandled
type: boolean
stability: stable
diff --git a/model/aws/registry.yaml b/model/aws/registry.yaml
index 75ebeee669..43e736725a 100644
--- a/model/aws/registry.yaml
+++ b/model/aws/registry.yaml
@@ -303,8 +303,6 @@ groups:
stability: experimental
brief: >
The ID of a running ECS task. The ID MUST be extracted from `task.arn`.
- requirement_level:
- conditionally_required: If and only if `task.arn` is populated.
examples:
[
"10838bed-421f-43ef-870a-f43feacbbb5b",
diff --git a/model/go/registry.yaml b/model/go/registry.yaml
index 5814394ca6..0caa69edb0 100644
--- a/model/go/registry.yaml
+++ b/model/go/registry.yaml
@@ -19,6 +19,5 @@ groups:
value: 'other'
brief: 'Memory used by the Go runtime, excluding other categories of memory usage described in this enumeration.'
stability: experimental
- requirement_level: recommended
brief: The type of memory.
examples: ["other", "stack"]
diff --git a/model/process/registry.yaml b/model/process/registry.yaml
index d2df832b28..5220f72867 100644
--- a/model/process/registry.yaml
+++ b/model/process/registry.yaml
@@ -113,8 +113,6 @@ groups:
This field can be useful for querying or performing bucket analysis on how many
arguments were provided to start a process. More arguments may be an indication
of suspicious activity.
- requirement_level:
- recommended: if `process.command_args` is populated.
examples: [4]
- id: process.owner
type: string
diff --git a/model/telemetry/registry.yaml b/model/telemetry/registry.yaml
index f5a4dc88bf..2cf3937501 100644
--- a/model/telemetry/registry.yaml
+++ b/model/telemetry/registry.yaml
@@ -8,7 +8,6 @@ groups:
- id: telemetry.sdk.name
type: string
stability: stable
- requirement_level: required
brief: >
The name of the telemetry SDK as defined above.
note: |
@@ -59,13 +58,11 @@ groups:
value: "webjs"
stability: stable
stability: stable
- requirement_level: required
brief: >
The language of the telemetry SDK.
- id: telemetry.sdk.version
type: string
stability: stable
- requirement_level: required
brief: >
The version string of the telemetry SDK.
examples: ["1.2.3"]
diff --git a/policies/registry.rego b/policies/registry.rego
index da1a5f4b0d..fccafd9b79 100644
--- a/policies/registry.rego
+++ b/policies/registry.rego
@@ -55,6 +55,20 @@ deny[attr_registry_violation(description, group.id, attr.ref)] {
description := sprintf("Registry group '%s' references attribute '%s'. Registry groups can only define new attributes.", [group.id, attr.ref])
}
+# We don't allow attribute definitions to have requirement_level
+deny[attr_registry_violation(description, group.id, attr.id)] {
+ group := input.groups[_]
+ startswith(group.id, "registry.")
+
+ attr := group.attributes[_]
+
+ # TODO: requirement_level defaults to recommended - no way to check if it's not set.
+ attr.requirement_level != "recommended"
+
+ # TODO (https://github.com/open-telemetry/weaver/issues/279): provide other violation properties once weaver supports it.
+ description := sprintf("Attribute definition '%s' has requirement_level set to %s. Only attribute references can set requirement_level.", [attr.id, attr.requirement_level])
+}
+
get_attribute_name(attr, group) = name {
full_name = concat(".", [group.prefix, attr.id])
diff --git a/policies_test/registry_test.rego b/policies_test/registry_test.rego
index 72d042e6e9..ce715cde3b 100644
--- a/policies_test/registry_test.rego
+++ b/policies_test/registry_test.rego
@@ -22,3 +22,9 @@ test_attribute_refs if {
count(before_resolution.deny) > 0 with input as {"groups": [{"id": "registry.foo", "attributes": [{"ref": "foo"}]}]}
count(before_resolution.deny) == 0 with input as {"groups": [{"id": "not_registry", "attributes": [{"ref": "foo"}]}]}
}
+
+test_attribute_requirement_levels if {
+ count(before_resolution.deny) > 0 with input as {"groups": [{"id": "registry.foo", "attributes": [{"id": "foo", "requirement_level": "required"}]}]}
+ count(before_resolution.deny) > 0 with input as {"groups": [{"id": "registry.foo", "attributes": [{"id": "foo", "requirement_level": {"recommended": "if available"}}]}]}
+ count(before_resolution.deny) == 0 with input as {"groups": [{"id": "not_registry", "attributes": [{"ref": "foo", "requirement_level": "required"}]}]}
+}
From 5a136795df8d298cca0505851af1c5d88ef86651 Mon Sep 17 00:00:00 2001
From: Trask Stalnaker
Date: Mon, 25 Nov 2024 09:28:46 -0800
Subject: [PATCH 11/32] Relax `server.port` requirement level on HTTP server
spans (#1591)
Co-authored-by: Liudmila Molkova
---
.chloggen/1591.yaml | 22 ++++++++++++++++++++++
docs/http/http-spans.md | 2 +-
model/http/common.yaml | 2 +-
3 files changed, 24 insertions(+), 2 deletions(-)
create mode 100644 .chloggen/1591.yaml
diff --git a/.chloggen/1591.yaml b/.chloggen/1591.yaml
new file mode 100644
index 0000000000..e035bbbb24
--- /dev/null
+++ b/.chloggen/1591.yaml
@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: http
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Relax `server.port` requirement level on HTTP server spans
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [ 1387 ]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md
index 37781049ea..fbca1be347 100644
--- a/docs/http/http-spans.md
+++ b/docs/http/http-spans.md
@@ -404,7 +404,7 @@ For an HTTP server span, `SpanKind` MUST be `SERVER`.
| [`http.response.status_code`](/docs/attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` If and only if one was received/sent. |  |
| [`http.route`](/docs/attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [6] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` If and only if it's available |  |
| [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [7] | `http`; `spdy` | `Conditionally Required` [8] |  |
-| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. |  |
+| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Conditionally Required` If available and `server.address` is set. |  |
| [`url.query`](/docs/attributes-registry/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [10] | `q=OpenTelemetry` | `Conditionally Required` If and only if one was received/sent. |  |
| [`client.address`](/docs/attributes-registry/client.md) | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [11] | `83.164.160.102` | `Recommended` |  |
| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
diff --git a/model/http/common.yaml b/model/http/common.yaml
index bf85efe255..7af01d2a59 100644
--- a/model/http/common.yaml
+++ b/model/http/common.yaml
@@ -79,7 +79,7 @@ groups:
note: >
See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
requirement_level:
- conditionally_required: If `server.address` is set.
+ conditionally_required: If available and `server.address` is set.
- ref: url.scheme
requirement_level: required
examples: ["http", "https"]
From b75c8c26d75859950a5ec7fed4e148544c9ece6a Mon Sep 17 00:00:00 2001
From: Roger Coll
Date: Mon, 25 Nov 2024 18:37:30 +0100
Subject: [PATCH 12/32] Add Linux process cgroup attribute (#1364)
Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Co-authored-by: Liudmila Molkova
---
.chloggen/add_process_cgroup.yaml | 22 ++++++++++++++++++++++
docs/attributes-registry/process.md | 11 +++++++++++
docs/resource/process.md | 3 +++
model/process/registry.yaml | 17 +++++++++++++++++
model/process/resources.yaml | 1 +
5 files changed, 54 insertions(+)
create mode 100755 .chloggen/add_process_cgroup.yaml
diff --git a/.chloggen/add_process_cgroup.yaml b/.chloggen/add_process_cgroup.yaml
new file mode 100755
index 0000000000..5f32a6ac9c
--- /dev/null
+++ b/.chloggen/add_process_cgroup.yaml
@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: 'enhancement'
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: linux
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add linux.process.cgroup attribute
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1357]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/docs/attributes-registry/process.md b/docs/attributes-registry/process.md
index 994792206c..31ef1a611a 100644
--- a/docs/attributes-registry/process.md
+++ b/docs/attributes-registry/process.md
@@ -7,6 +7,7 @@
# Process
- [Process Attributes](#process-attributes)
+- [Process Linux Attributes](#process-linux-attributes)
- [Deprecated Process Attributes](#deprecated-process-attributes)
## Process Attributes
@@ -72,6 +73,16 @@ An operating system process.
| `major` | major |  |
| `minor` | minor |  |
+## Process Linux Attributes
+
+Describes Linux Process attributes
+
+| Attribute | Type | Description | Examples | Stability |
+|---|---|---|---|---|
+| `process.linux.cgroup` | string | The control group associated with the process. [4] | `1:name=systemd:/user.slice/user-1000.slice/session-3.scope`; `0::/user.slice/user-1000.slice/user@1000.service/tmux-spawn-0267755b-4639-4a27-90ed-f19f88e53748.scope` |  |
+
+**[4] `process.linux.cgroup`:** Control groups (cgroups) are a kernel feature used to organize and manage process resources. This attribute provides the path(s) to the cgroup(s) associated with the process, which should match the contents of the [/proc//cgroup](https://man7.org/linux/man-pages/man7/cgroups.7.html) file.
+
## Deprecated Process Attributes
Deprecated process attributes.
diff --git a/docs/resource/process.md b/docs/resource/process.md
index ba90335671..9f50e0e6b7 100644
--- a/docs/resource/process.md
+++ b/docs/resource/process.md
@@ -42,6 +42,7 @@
| [`process.command_line`](/docs/attributes-registry/process.md) | string | The full command used to launch the process as a single string representing the full command. On Windows, can be set to the result of `GetCommandLineW`. Do not set this if you have to assemble it just for monitoring; use `process.command_args` instead. | `C:\cmd\otecol --config="my directory\config.yaml"` | `Conditionally Required` [3] |  |
| [`process.executable.name`](/docs/attributes-registry/process.md) | string | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | `Conditionally Required` [4] |  |
| [`process.executable.path`](/docs/attributes-registry/process.md) | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | `Conditionally Required` [5] |  |
+| [`process.linux.cgroup`](/docs/attributes-registry/process.md) | string | The control group associated with the process. [6] | `1:name=systemd:/user.slice/user-1000.slice/session-3.scope`; `0::/user.slice/user-1000.slice/user@1000.service/tmux-spawn-0267755b-4639-4a27-90ed-f19f88e53748.scope` | `Recommended` |  |
| [`process.owner`](/docs/attributes-registry/process.md) | string | The username of the user that owns the process. | `root` | `Recommended` |  |
| [`process.parent_pid`](/docs/attributes-registry/process.md) | int | Parent Process identifier (PPID). | `111` | `Recommended` |  |
| [`process.pid`](/docs/attributes-registry/process.md) | int | Process identifier (PID). | `1234` | `Recommended` |  |
@@ -56,6 +57,8 @@
**[5] `process.executable.path`:** See [Selecting process attributes](#selecting-process-attributes) for details.
+**[6] `process.linux.cgroup`:** Control groups (cgroups) are a kernel feature used to organize and manage process resources. This attribute provides the path(s) to the cgroup(s) associated with the process, which should match the contents of the [/proc//cgroup](https://man7.org/linux/man-pages/man7/cgroups.7.html) file.
+
diff --git a/model/process/registry.yaml b/model/process/registry.yaml
index 5220f72867..ebcd9012e8 100644
--- a/model/process/registry.yaml
+++ b/model/process/registry.yaml
@@ -239,3 +239,20 @@ groups:
value: 'minor'
stability: experimental
stability: experimental
+ # process.linux* attribute group
+ - id: registry.process.linux
+ type: attribute_group
+ brief: "Describes Linux Process attributes"
+ attributes:
+ - id: process.linux.cgroup
+ type: string
+ stability: experimental
+ brief: The control group associated with the process.
+ examples: ["1:name=systemd:/user.slice/user-1000.slice/session-3.scope", "0::/user.slice/user-1000.slice/user@1000.service/tmux-spawn-0267755b-4639-4a27-90ed-f19f88e53748.scope"]
+ note: >
+ Control groups (cgroups) are a kernel feature used to organize and
+ manage process resources. This attribute provides the path(s) to the
+ cgroup(s) associated with the process, which should match the contents
+ of the
+ [/proc//cgroup](https://man7.org/linux/man-pages/man7/cgroups.7.html)
+ file.
diff --git a/model/process/resources.yaml b/model/process/resources.yaml
index 3c015d607e..3b3155439f 100644
--- a/model/process/resources.yaml
+++ b/model/process/resources.yaml
@@ -23,6 +23,7 @@ groups:
requirement_level:
conditionally_required: See [Selecting process attributes](#selecting-process-attributes) for details.
- ref: process.owner
+ - ref: process.linux.cgroup
- id: resource.process.runtime
type: resource
From f5bb5b36914ee141f08fa113f101de38ebc7e4ab Mon Sep 17 00:00:00 2001
From: Liudmila Molkova
Date: Mon, 25 Nov 2024 09:47:09 -0800
Subject: [PATCH 13/32] Add missing sections and owners to codeowners files
(#1607)
---
.github/CODEOWNERS | 23 +++++++++++++++++--
docs/feature-flags/feature-flags-logs.md | 2 +-
.../deprecated/registry-deprecated.yaml | 0
.../{feature-flag => feature-flags}/logs.yaml | 0
.../registry.yaml | 0
5 files changed, 22 insertions(+), 3 deletions(-)
rename model/{feature-flag => feature-flags}/deprecated/registry-deprecated.yaml (100%)
rename model/{feature-flag => feature-flags}/logs.yaml (100%)
rename model/{feature-flag => feature-flags}/registry.yaml (100%)
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index c0858bd806..af09caa17e 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -21,7 +21,6 @@
# Logs and events semantic conventions
/docs/exceptions/exceptions-logs.md @open-telemetry/specs-semconv-approvers @tigrannajaryan
-/docs/feature-flags/feature-flags-logs.md @open-telemetry/specs-semconv-approvers @tigrannajaryan
/docs/general/events-general.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-event-approvers @tigrannajaryan
/docs/general/logs-general.md @open-telemetry/specs-semconv-approvers @tigrannajaryan
/docs/logs/ @open-telemetry/specs-semconv-approvers @tigrannajaryan
@@ -43,9 +42,11 @@
/model/user-agent/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
# System semantic conventions
+/docs/process/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers @open-telemetry/semconv-security-approvers
/docs/system/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
/docs/resource/host.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
/model/host/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
+/model/process/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers @open-telemetry/semconv-security-approvers
/model/system/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
# Mobile semantic conventions
@@ -76,7 +77,7 @@
/model/dns/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
/model/file/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
# /model/network/ is defined in HTTP section
-/model/process/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
+# /model/process/ is defined in system section
/model/tls/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
/model/user/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
@@ -88,3 +89,21 @@
/model/deployment/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
/model/test/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
/model/vcs/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
+
+# Database semantic conventions
+/docs/database/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-db-approvers
+/model/database/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-db-approvers
+
+# Messaging semantic conventions
+/docs/messaging/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-messaging-approvers
+/model/messaging/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-messaging-approvers
+
+# Feature flag semantic conventions
+/docs/feature-flags/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-feature-flag-approvers
+/model/feature-flags/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-feature-flag-approvers
+
+# Tooling
+/policies/ @open-telemetry/specs-semconv-approvers @open-telemetry/weaver-maintainers
+/policies_test/ @open-telemetry/specs-semconv-approvers @open-telemetry/weaver-maintainers
+/templates/ @open-telemetry/specs-semconv-approvers @open-telemetry/weaver-maintainers
+/internal/ @open-telemetry/specs-semconv-approvers @open-telemetry/weaver-maintainers
diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md
index fcebce470c..b893a3f1a3 100644
--- a/docs/feature-flags/feature-flags-logs.md
+++ b/docs/feature-flags/feature-flags-logs.md
@@ -14,7 +14,7 @@ such as when the application loads or on a timer.
## Motivation
-Features flags are commonly used in modern applications to decouple feature releases from deployments.
+Feature flags are commonly used in modern applications to decouple feature releases from deployments.
Many feature flagging tools support the ability to update flag configurations in near real-time from a remote feature flag management service.
They also commonly allow rulesets to be defined that return values based on contextual information.
For example, a feature could be enabled only for a specific subset of users based on context (e.g. users email domain, membership tier, country).
diff --git a/model/feature-flag/deprecated/registry-deprecated.yaml b/model/feature-flags/deprecated/registry-deprecated.yaml
similarity index 100%
rename from model/feature-flag/deprecated/registry-deprecated.yaml
rename to model/feature-flags/deprecated/registry-deprecated.yaml
diff --git a/model/feature-flag/logs.yaml b/model/feature-flags/logs.yaml
similarity index 100%
rename from model/feature-flag/logs.yaml
rename to model/feature-flags/logs.yaml
diff --git a/model/feature-flag/registry.yaml b/model/feature-flags/registry.yaml
similarity index 100%
rename from model/feature-flag/registry.yaml
rename to model/feature-flags/registry.yaml
From ab1362c44ea6f523398aa4d8b47120580365cc81 Mon Sep 17 00:00:00 2001
From: Liudmila Molkova
Date: Mon, 25 Nov 2024 10:45:14 -0800
Subject: [PATCH 14/32] Fix broken anchors, remove `en` from some links (#1610)
---
docs/attributes-registry/db.md | 2 +-
docs/attributes-registry/geo.md | 8 ++++----
docs/attributes-registry/url.md | 4 ++--
docs/database/cassandra.md | 2 +-
docs/database/cosmosdb.md | 4 ++--
docs/database/database-metrics.md | 4 ++--
docs/database/database-spans.md | 4 ++--
docs/database/elasticsearch.md | 2 +-
docs/database/mariadb.md | 2 +-
docs/database/mssql.md | 2 +-
docs/database/mysql.md | 2 +-
docs/database/postgresql.md | 2 +-
docs/database/sql.md | 2 +-
docs/general/attribute-naming.md | 4 ++--
docs/http/http-spans.md | 4 ++--
docs/messaging/azure-messaging.md | 2 +-
docs/resource/process.md | 2 +-
docs/system/hardware-metrics.md | 2 +-
docs/url/url.md | 4 ++--
model/database/registry.yaml | 2 +-
model/geo/registry.yaml | 8 ++++----
model/messaging/spans.yaml | 2 +-
model/url/registry.yaml | 4 ++--
23 files changed, 37 insertions(+), 37 deletions(-)
diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md
index eb72e22f2b..cf2f7fc965 100644
--- a/docs/attributes-registry/db.md
+++ b/docs/attributes-registry/db.md
@@ -76,7 +76,7 @@ If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD
This attribute has stability level RELEASE CANDIDATE.
**[6] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
-Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
+Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[7] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
diff --git a/docs/attributes-registry/geo.md b/docs/attributes-registry/geo.md
index b6e424f764..c86484d9b3 100644
--- a/docs/attributes-registry/geo.md
+++ b/docs/attributes-registry/geo.md
@@ -14,12 +14,12 @@ Note: Geo attributes are typically used under another namespace, such as client.
| Attribute | Type | Description | Examples | Stability |
|---|---|---|---|---|
| `geo.continent.code` | string | Two-letter code representing continent’s name. | `AF`; `AN`; `AS` |  |
-| `geo.country.iso_code` | string | Two-letter ISO Country Code ([ISO 3166-1 alpha2](https://en.wikipedia.org/wiki/ISO_3166-1#Codes)). | `CA` |  |
+| `geo.country.iso_code` | string | Two-letter ISO Country Code ([ISO 3166-1 alpha2](https://wikipedia.org/wiki/ISO_3166-1#Codes)). | `CA` |  |
| `geo.locality.name` | string | Locality name. Represents the name of a city, town, village, or similar populated place. | `Montreal`; `Berlin` |  |
-| `geo.location.lat` | double | Latitude of the geo location in [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84). | `45.505918` |  |
-| `geo.location.lon` | double | Longitude of the geo location in [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84). | `-73.61483` |  |
+| `geo.location.lat` | double | Latitude of the geo location in [WGS84](https://wikipedia.org/wiki/World_Geodetic_System#WGS84). | `45.505918` |  |
+| `geo.location.lon` | double | Longitude of the geo location in [WGS84](https://wikipedia.org/wiki/World_Geodetic_System#WGS84). | `-73.61483` |  |
| `geo.postal_code` | string | Postal code associated with the location. Values appropriate for this field may also be known as a postcode or ZIP code and will vary widely from country to country. | `94040` |  |
-| `geo.region.iso_code` | string | Region ISO code ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)). | `CA-QC` |  |
+| `geo.region.iso_code` | string | Region ISO code ([ISO 3166-2](https://wikipedia.org/wiki/ISO_3166-2)). | `CA-QC` |  |
---
diff --git a/docs/attributes-registry/url.md b/docs/attributes-registry/url.md
index 963184f19c..4cae9caa79 100644
--- a/docs/attributes-registry/url.md
+++ b/docs/attributes-registry/url.md
@@ -46,7 +46,7 @@ value `REDACTED`:
* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
-* [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token)
+* [`sig`](https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token)
* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls)
This list is subject to change over time.
@@ -66,7 +66,7 @@ Query string values for the following keys SHOULD be redacted by default and rep
* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
-* [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token)
+* [`sig`](https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token)
* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls)
This list is subject to change over time.
diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md
index ccd22f2b36..1e88e72c83 100644
--- a/docs/database/cassandra.md
+++ b/docs/database/cassandra.md
@@ -100,7 +100,7 @@ Instrumentations SHOULD document how `error.type` is populated.
This attribute has stability level RELEASE CANDIDATE.
**[12] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
-Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
+Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[13] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md
index f2d77b26bc..a4784aaa6a 100644
--- a/docs/database/cosmosdb.md
+++ b/docs/database/cosmosdb.md
@@ -209,7 +209,7 @@ Instrumentations SHOULD document how `error.type` is populated.
This attribute has stability level RELEASE CANDIDATE.
**[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
-Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
+Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
@@ -311,7 +311,7 @@ Refer [db.client.cosmosdb.operation.request_charge](#metric-dbclientcosmosdboper
This metric is [required][MetricRequired].
-It captures the number of items returned by a query or feed operation in Azure Cosmos DB. It helps identify response sizes that may contribute to high latency, increased memory/CPU usage, or network call failures. This metric follows the common [db.client.response.returned_rows](/docs/database/database-metrics.md##metric-dbclientresponsereturned_rows) definition.
+It captures the number of items returned by a query or feed operation in Azure Cosmos DB. It helps identify response sizes that may contribute to high latency, increased memory/CPU usage, or network call failures. This metric follows the common [db.client.response.returned_rows](/docs/database/database-metrics.md#metric-dbclientresponsereturned_rows) definition.
Refer [db.client.cosmosdb.operation.request_charge](#metric-dbclientcosmosdboperationrequest_charge) metrics for dimensions.
diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md
index 858cec0a7f..0fecfffeaf 100644
--- a/docs/database/database-metrics.md
+++ b/docs/database/database-metrics.md
@@ -154,7 +154,7 @@ Instrumentations SHOULD document how `error.type` is populated.
**[11] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[12] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
-Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
+Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[13] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
@@ -343,7 +343,7 @@ Instrumentations SHOULD document how `error.type` is populated.
**[11] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[12] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
-Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
+Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[13] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md
index 995b058697..cec4406b71 100644
--- a/docs/database/database-spans.md
+++ b/docs/database/database-spans.md
@@ -175,7 +175,7 @@ Instrumentations SHOULD document how `error.type` is populated.
This attribute has stability level RELEASE CANDIDATE.
**[13] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
-Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
+Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[14] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
@@ -307,7 +307,7 @@ in which case the instrumentation MAY choose a different placeholder.
Placeholders in a parameterized query SHOULD not be sanitized. E.g. `where id = $1` can be captured as is.
-[IN-clauses](https://en.wikipedia.org/wiki/Where_(SQL)#IN) MAY be collapsed during sanitization,
+[IN-clauses](https://wikipedia.org/wiki/Where_(SQL)#IN) MAY be collapsed during sanitization,
e.g. from `IN (?, ?, ?, ?)` to `IN (?)`, as this can help with extremely long IN-clauses,
and can help control cardinality for users who choose to (optionally) add `db.query.text` to their metric attributes.
diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md
index 34582635b0..191397bec8 100644
--- a/docs/database/elasticsearch.md
+++ b/docs/database/elasticsearch.md
@@ -72,7 +72,7 @@ value `REDACTED`:
* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
-* [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token)
+* [`sig`](https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token)
* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls)
This list is subject to change over time.
diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md
index b78e0f3edf..1b8818b664 100644
--- a/docs/database/mariadb.md
+++ b/docs/database/mariadb.md
@@ -115,7 +115,7 @@ Instrumentations SHOULD document how `error.type` is populated.
This attribute has stability level RELEASE CANDIDATE.
**[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
-Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
+Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
diff --git a/docs/database/mssql.md b/docs/database/mssql.md
index 8fea8253e7..0bb470dc9e 100644
--- a/docs/database/mssql.md
+++ b/docs/database/mssql.md
@@ -85,7 +85,7 @@ Instrumentations SHOULD document how `error.type` is populated.
This attribute has stability level RELEASE CANDIDATE.
**[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
-Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
+Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
diff --git a/docs/database/mysql.md b/docs/database/mysql.md
index 9124813138..60b3d795f2 100644
--- a/docs/database/mysql.md
+++ b/docs/database/mysql.md
@@ -115,7 +115,7 @@ Instrumentations SHOULD document how `error.type` is populated.
This attribute has stability level RELEASE CANDIDATE.
**[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
-Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
+Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md
index 6dbeba3292..249e3a0481 100644
--- a/docs/database/postgresql.md
+++ b/docs/database/postgresql.md
@@ -122,7 +122,7 @@ Instrumentations SHOULD document how `error.type` is populated.
This attribute has stability level RELEASE CANDIDATE.
**[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
-Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
+Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
diff --git a/docs/database/sql.md b/docs/database/sql.md
index 481aea78b2..92df4eef51 100644
--- a/docs/database/sql.md
+++ b/docs/database/sql.md
@@ -147,7 +147,7 @@ Instrumentations SHOULD document how `error.type` is populated.
This attribute has stability level RELEASE CANDIDATE.
**[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
-Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section.
+Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section.
This attribute has stability level RELEASE CANDIDATE.
**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
diff --git a/docs/general/attribute-naming.md b/docs/general/attribute-naming.md
index cded4a49ca..34e84d2f9d 100644
--- a/docs/general/attribute-naming.md
+++ b/docs/general/attribute-naming.md
@@ -111,7 +111,7 @@ denote old attribute names in rename operations).
- Semantic conventions MUST limit names to printable Basic Latin characters
(more precisely to
- [U+0021 .. U+007E]()
+ [U+0021 .. U+007E]()
subset of Unicode code points). It is recommended to further limit names to
the following Unicode code points: Latin alphabet, Numeric, Underscore, Dot
(as namespace delimiter).
@@ -156,7 +156,7 @@ options:
It is recommended to limit names to printable Basic Latin characters (more
precisely to
-[U+0021 .. U+007E]()
+[U+0021 .. U+007E]()
subset of Unicode code points).
## otel.\* Namespace
diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md
index fbca1be347..967db6d643 100644
--- a/docs/http/http-spans.md
+++ b/docs/http/http-spans.md
@@ -199,7 +199,7 @@ value `REDACTED`:
* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
-* [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token)
+* [`sig`](https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token)
* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls)
This list is subject to change over time.
@@ -478,7 +478,7 @@ Query string values for the following keys SHOULD be redacted by default and rep
* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
-* [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token)
+* [`sig`](https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token)
* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls)
This list is subject to change over time.
diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md
index 34bf545fab..2bae085ae8 100644
--- a/docs/messaging/azure-messaging.md
+++ b/docs/messaging/azure-messaging.md
@@ -179,7 +179,7 @@ The following additional attributes are defined:
| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | Azure Event Hubs operation name. [1] | `send`; `receive`; `checkpoint` | `Required` |  |
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | `Conditionally Required` If and only if the messaging operation has failed. |  |
| [`messaging.batch.message_count`](/docs/attributes-registry/messaging.md) | int | The number of messages sent, received, or processed in the scope of the batching operation. [3] | `0`; `1`; `2` | `Conditionally Required` [4] |  |
-| [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) | string | Azure Event Hubs [consumer group name](https://learn.microsoft.com/en-us/azure/event-hubs/event-hubs-features#consumer-groups). | `my-group`; `indexer` | `Conditionally Required` On consumer spans. |  |
+| [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) | string | Azure Event Hubs [consumer group name](https://learn.microsoft.com/azure/event-hubs/event-hubs-features#consumer-groups). | `my-group`; `indexer` | `Conditionally Required` On consumer spans. |  |
| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [5] | `MyQueue`; `MyTopic` | `Conditionally Required` [6] |  |
| [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | String representation of the partition id messages are sent to or received from, unique within the Event Hub. | `1` | `Conditionally Required` If available. |  |
| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `create`; `send`; `receive` | `Conditionally Required` If applicable. |  |
diff --git a/docs/resource/process.md b/docs/resource/process.md
index 9f50e0e6b7..52623f2a50 100644
--- a/docs/resource/process.md
+++ b/docs/resource/process.md
@@ -198,7 +198,7 @@ Examples for some JavaScript runtimes
- `process.runtime.name` - Fill in the value by the name of runtime.
- `process.runtime.version` - Fill in the value of `System.Environment.Version` for .NET,
- determine version based on the [registry values](https://learn.microsoft.com/en-us/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed#query-the-registry-using-code)
+ determine version based on the [registry values](https://learn.microsoft.com/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed#query-the-registry-using-code)
for .NET Framework
- `process.runtime.description` - Fill in the values of `System.Runtime.InteropServices.RuntimeInformation.FrameworkDescription`.
diff --git a/docs/system/hardware-metrics.md b/docs/system/hardware-metrics.md
index a7b7039cc1..f54c281300 100644
--- a/docs/system/hardware-metrics.md
+++ b/docs/system/hardware-metrics.md
@@ -277,7 +277,7 @@ Additional **Recommended** attributes:
| | | | | | `hw.type` (**Required**) | `physical_disk` |
| `hw.physical_disk.endurance_utilization` | Endurance remaining for this SSD disk | 1 | Gauge | Double | `state` (**Required**) | `remaining` |
| `hw.physical_disk.size` | Size of the disk | By | UpDownCounter | Int64 | | |
-| `hw.physical_disk.smart` | Value of the corresponding [S.M.A.R.T.](https://en.wikipedia.org/wiki/S.M.A.R.T.) attribute | 1 | Gauge | Int | `smart_attribute` (Recommended) | `Seek Error Rate`, `Spin Retry Count`, etc. |
+| `hw.physical_disk.smart` | Value of the corresponding [S.M.A.R.T.](https://wikipedia.org/wiki/S.M.A.R.T.) attribute | 1 | Gauge | Int | `smart_attribute` (Recommended) | `Seek Error Rate`, `Spin Retry Count`, etc. |
| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `predicted_failure` |
| | | | | | `hw.type` (**Required**) | `physical_disk` |
diff --git a/docs/url/url.md b/docs/url/url.md
index 4a21d5d289..2301c56a7a 100644
--- a/docs/url/url.md
+++ b/docs/url/url.md
@@ -53,7 +53,7 @@ value `REDACTED`:
* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
-* [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token)
+* [`sig`](https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token)
* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls)
This list is subject to change over time.
@@ -70,7 +70,7 @@ Query string values for the following keys SHOULD be redacted by default and rep
* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
-* [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token)
+* [`sig`](https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token)
* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls)
This list is subject to change over time.
diff --git a/model/database/registry.yaml b/model/database/registry.yaml
index a453421878..f93fa98fbb 100644
--- a/model/database/registry.yaml
+++ b/model/database/registry.yaml
@@ -115,7 +115,7 @@ groups:
Summary may be available to the instrumentation through
instrumentation hooks or other means. If it is not available, instrumentations
that support query parsing SHOULD generate a summary following
- [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text)
+ [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text)
section.
This attribute has stability level RELEASE CANDIDATE.
diff --git a/model/geo/registry.yaml b/model/geo/registry.yaml
index 41cb4afb38..e370fbd4df 100644
--- a/model/geo/registry.yaml
+++ b/model/geo/registry.yaml
@@ -54,19 +54,19 @@ groups:
stability: experimental
type: string
brief: >
- Two-letter ISO Country Code ([ISO 3166-1 alpha2](https://en.wikipedia.org/wiki/ISO_3166-1#Codes)).
+ Two-letter ISO Country Code ([ISO 3166-1 alpha2](https://wikipedia.org/wiki/ISO_3166-1#Codes)).
examples: [ 'CA' ]
- id: geo.location.lon
stability: experimental
type: double
brief: >
- Longitude of the geo location in [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84).
+ Longitude of the geo location in [WGS84](https://wikipedia.org/wiki/World_Geodetic_System#WGS84).
examples: [ -73.614830 ]
- id: geo.location.lat
stability: experimental
type: double
brief: >
- Latitude of the geo location in [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84).
+ Latitude of the geo location in [WGS84](https://wikipedia.org/wiki/World_Geodetic_System#WGS84).
examples: [ 45.505918 ]
- id: geo.postal_code
stability: experimental
@@ -79,5 +79,5 @@ groups:
stability: experimental
type: string
brief: >
- Region ISO code ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)).
+ Region ISO code ([ISO 3166-2](https://wikipedia.org/wiki/ISO_3166-2)).
examples: [ 'CA-QC' ]
diff --git a/model/messaging/spans.yaml b/model/messaging/spans.yaml
index 1e5dc30413..a5b76e0b0b 100644
--- a/model/messaging/spans.yaml
+++ b/model/messaging/spans.yaml
@@ -265,7 +265,7 @@ groups:
Attributes for Azure Event Hubs
attributes:
- ref: messaging.consumer.group.name
- brief: "Azure Event Hubs [consumer group name](https://learn.microsoft.com/en-us/azure/event-hubs/event-hubs-features#consumer-groups)."
+ brief: "Azure Event Hubs [consumer group name](https://learn.microsoft.com/azure/event-hubs/event-hubs-features#consumer-groups)."
note: ""
requirement_level:
conditionally_required: On consumer spans.
diff --git a/model/url/registry.yaml b/model/url/registry.yaml
index d57c04733e..8bafe190cb 100644
--- a/model/url/registry.yaml
+++ b/model/url/registry.yaml
@@ -57,7 +57,7 @@ groups:
* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
- * [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token)
+ * [`sig`](https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token)
* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls)
This list is subject to change over time.
@@ -110,7 +110,7 @@ groups:
* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
- * [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token)
+ * [`sig`](https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token)
* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls)
This list is subject to change over time.
From 3fa52acca3ec1530f9b88a38a29bfd876ec2205d Mon Sep 17 00:00:00 2001
From: Trask Stalnaker
Date: Mon, 25 Nov 2024 11:56:09 -0800
Subject: [PATCH 15/32] Don't capture `db.operation.name` and
`db.collection.name` from query formats that support multiples (#1566)
---
.chloggen/1566.yaml | 22 ++++++++++
docs/attributes-registry/db.md | 16 ++-----
docs/database/cassandra.md | 16 ++-----
docs/database/cosmosdb.md | 16 ++++---
docs/database/database-metrics.md | 32 ++++----------
docs/database/database-spans.md | 16 ++-----
docs/database/hbase.md | 6 +--
docs/database/mariadb.md | 69 +++++++++---------------------
docs/database/mongodb.md | 10 +----
docs/database/mssql.md | 69 +++++++++---------------------
docs/database/mysql.md | 69 +++++++++---------------------
docs/database/postgresql.md | 69 +++++++++---------------------
docs/database/redis.md | 6 +--
docs/database/sql.md | 71 +++++++++----------------------
model/database/common.yaml | 39 +++++++++++------
model/database/registry.yaml | 16 ++-----
model/database/spans.yaml | 50 ++++++++++++++++------
17 files changed, 230 insertions(+), 362 deletions(-)
create mode 100644 .chloggen/1566.yaml
diff --git a/.chloggen/1566.yaml b/.chloggen/1566.yaml
new file mode 100644
index 0000000000..5b82a55e2a
--- /dev/null
+++ b/.chloggen/1566.yaml
@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: breaking
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: db
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Don't capture `db.operation.name` and `db.collection.name` from query formats that support multiples.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [ 1566 ]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md
index cf2f7fc965..381ead2fda 100644
--- a/docs/attributes-registry/db.md
+++ b/docs/attributes-registry/db.md
@@ -34,18 +34,12 @@ This group defines the attributes used to describe telemetry in the context of d
**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-A single database query may involve multiple collections.
-
-If the collection name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single collection and it SHOULD match the value provided in
-the query text including any schema and database name prefix.
+The collection name SHOULD NOT be extracted from `db.query.text`,
+unless the query format is known to only ever have a single collection name present.
For batch operations, if the individual operations are known to have the same collection name
then that collection name SHOULD be used.
-If the operation or query involves multiple collections, `db.collection.name`
-SHOULD NOT be captured.
-
This attribute has stability level RELEASE CANDIDATE.
**[2] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
@@ -59,10 +53,8 @@ This attribute has stability level RELEASE CANDIDATE.
**[4] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization.
-A single database query may involve multiple operations. If the operation
-name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single operation or when the operation name describing the
-whole query is available by other means.
+The operation name SHOULD NOT be extracted from `db.query.text`,
+unless the query format is known to only ever have a single operation name present.
For batch operations, if the individual operations are known to have the same operation name
then that operation name SHOULD be used prepended by `BATCH `,
diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md
index 1e88e72c83..270a90c2aa 100644
--- a/docs/database/cassandra.md
+++ b/docs/database/cassandra.md
@@ -44,18 +44,12 @@ The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend a
**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-A single database query may involve multiple collections.
-
-If the collection name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single collection and it SHOULD match the value provided in
-the query text including any schema and database name prefix.
+The collection name SHOULD NOT be extracted from `db.query.text`,
+unless the query format is known to only ever have a single collection name present.
For batch operations, if the individual operations are known to have the same collection name
then that collection name SHOULD be used.
-If the operation or query involves multiple collections, `db.collection.name`
-SHOULD NOT be captured.
-
This attribute has stability level RELEASE CANDIDATE.
**[2] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
@@ -68,10 +62,8 @@ This attribute has stability level RELEASE CANDIDATE.
**[4] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization.
-A single database query may involve multiple operations. If the operation
-name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single operation or when the operation name describing the
-whole query is available by other means.
+The operation name SHOULD NOT be extracted from `db.query.text`,
+unless the query format is known to only ever have a single operation name present.
For batch operations, if the individual operations are known to have the same operation name
then that operation name SHOULD be used prepended by `BATCH `,
diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md
index a4784aaa6a..941ffd5ad3 100644
--- a/docs/database/cosmosdb.md
+++ b/docs/database/cosmosdb.md
@@ -345,7 +345,7 @@ Explaining bucket configuration:
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`db.collection.name`](/docs/attributes-registry/db.md) | string | Cosmos DB container name. [1] | `public.users`; `customers` | `Conditionally Required` If available |  |
+| [`db.collection.name`](/docs/attributes-registry/db.md) | string | Cosmos DB container name. [1] | `public.users`; `customers` | `Conditionally Required` If available. |  |
| [`db.cosmosdb.consistency_level`](/docs/attributes-registry/db.md) | string | Account or request [consistency level](https://learn.microsoft.com/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong`; `Session` | `Conditionally Required` If available. |  |
| [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` when response was received and contained sub-code. |  |
| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. |  |
@@ -358,13 +358,19 @@ Explaining bucket configuration:
**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
+The collection name SHOULD NOT be extracted from `db.query.text`,
+unless the query format is known to only ever have a single collection name present.
+
+For batch operations, if the individual operations are known to have the same collection name
+then that collection name SHOULD be used.
+
+This attribute has stability level RELEASE CANDIDATE.
+
**[2] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization.
-A single database query may involve multiple operations. If the operation
-name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single operation or when the operation name describing the
-whole query is available by other means.
+The operation name SHOULD NOT be extracted from `db.query.text`,
+unless the query format is known to only ever have a single operation name present.
For batch operations, if the individual operations are known to have the same operation name
then that operation name SHOULD be used prepended by `BATCH `,
diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md
index 0fecfffeaf..e7d2597bef 100644
--- a/docs/database/database-metrics.md
+++ b/docs/database/database-metrics.md
@@ -101,18 +101,12 @@ This attribute has stability level RELEASE CANDIDATE.
**[2] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-A single database query may involve multiple collections.
-
-If the collection name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single collection and it SHOULD match the value provided in
-the query text including any schema and database name prefix.
+The collection name SHOULD NOT be extracted from `db.query.text`,
+unless the query format is known to only ever have a single collection name present.
For batch operations, if the individual operations are known to have the same collection name
then that collection name SHOULD be used.
-If the operation or query involves multiple collections, `db.collection.name`
-SHOULD NOT be captured.
-
This attribute has stability level RELEASE CANDIDATE.
**[3] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
@@ -125,10 +119,8 @@ This attribute has stability level RELEASE CANDIDATE.
**[5] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization.
-A single database query may involve multiple operations. If the operation
-name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single operation or when the operation name describing the
-whole query is available by other means.
+The operation name SHOULD NOT be extracted from `db.query.text`,
+unless the query format is known to only ever have a single operation name present.
For batch operations, if the individual operations are known to have the same operation name
then that operation name SHOULD be used prepended by `BATCH `,
@@ -290,18 +282,12 @@ This attribute has stability level RELEASE CANDIDATE.
**[2] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-A single database query may involve multiple collections.
-
-If the collection name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single collection and it SHOULD match the value provided in
-the query text including any schema and database name prefix.
+The collection name SHOULD NOT be extracted from `db.query.text`,
+unless the query format is known to only ever have a single collection name present.
For batch operations, if the individual operations are known to have the same collection name
then that collection name SHOULD be used.
-If the operation or query involves multiple collections, `db.collection.name`
-SHOULD NOT be captured.
-
This attribute has stability level RELEASE CANDIDATE.
**[3] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
@@ -314,10 +300,8 @@ This attribute has stability level RELEASE CANDIDATE.
**[5] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization.
-A single database query may involve multiple operations. If the operation
-name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single operation or when the operation name describing the
-whole query is available by other means.
+The operation name SHOULD NOT be extracted from `db.query.text`,
+unless the query format is known to only ever have a single operation name present.
For batch operations, if the individual operations are known to have the same operation name
then that operation name SHOULD be used prepended by `BATCH `,
diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md
index cec4406b71..597a9de6cf 100644
--- a/docs/database/database-spans.md
+++ b/docs/database/database-spans.md
@@ -119,18 +119,12 @@ This attribute has stability level RELEASE CANDIDATE.
**[2] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-A single database query may involve multiple collections.
-
-If the collection name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single collection and it SHOULD match the value provided in
-the query text including any schema and database name prefix.
+The collection name SHOULD NOT be extracted from `db.query.text`,
+unless the query format is known to only ever have a single collection name present.
For batch operations, if the individual operations are known to have the same collection name
then that collection name SHOULD be used.
-If the operation or query involves multiple collections, `db.collection.name`
-SHOULD NOT be captured.
-
This attribute has stability level RELEASE CANDIDATE.
**[3] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
@@ -143,10 +137,8 @@ This attribute has stability level RELEASE CANDIDATE.
**[5] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization.
-A single database query may involve multiple operations. If the operation
-name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single operation or when the operation name describing the
-whole query is available by other means.
+The operation name SHOULD NOT be extracted from `db.query.text`,
+unless the query format is known to only ever have a single operation name present.
For batch operations, if the individual operations are known to have the same operation name
then that operation name SHOULD be used prepended by `BATCH `,
diff --git a/docs/database/hbase.md b/docs/database/hbase.md
index e4bdb17443..ad7c89aaed 100644
--- a/docs/database/hbase.md
+++ b/docs/database/hbase.md
@@ -40,10 +40,8 @@ This attribute has stability level RELEASE CANDIDATE.
**[3] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization.
-A single database query may involve multiple operations. If the operation
-name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single operation or when the operation name describing the
-whole query is available by other means.
+The operation name SHOULD NOT be extracted from `db.query.text`,
+unless the query format is known to only ever have a single operation name present.
For batch operations, if the individual operations are known to have the same operation name
then that operation name SHOULD be used prepended by `BATCH `,
diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md
index 1b8818b664..aff44fdfb9 100644
--- a/docs/database/mariadb.md
+++ b/docs/database/mariadb.md
@@ -21,38 +21,18 @@ The Semantic Conventions for *MariaDB* extend and override the [Database Semanti
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of the SQL table that the operation is acting upon. [1] | `users`; `dbo.products` | `Conditionally Required` [2] |  |
-| [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection. [3] | `products`; `customers` | `Conditionally Required` If available without an additional network call. |  |
-| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `SELECT`; `INSERT`; `UPDATE`; `DELETE`; `CREATE`; `mystoredproc` | `Conditionally Required` [5] |  |
-| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [Maria DB error code](https://mariadb.com/kb/en/mariadb-error-code-reference/) represented as a string. [6] | `1008`; `3058` | `Conditionally Required` If response has ended with warning or an error. |  |
-| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [7] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. |  |
-| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [8] | `80`; `8080`; `443` | `Conditionally Required` [9] |  |
-| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [10] | `2`; `3`; `4` | `Recommended` |  |
-| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] |  |
-| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] |  |
+| [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection. [1] | `products`; `customers` | `Conditionally Required` If available without an additional network call. |  |
+| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [Maria DB error code](https://mariadb.com/kb/en/mariadb-error-code-reference/) represented as a string. [2] | `1008`; `3058` | `Conditionally Required` If response has ended with warning or an error. |  |
+| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. |  |
+| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` [5] |  |
+| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` |  |
+| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [8] |  |
+| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [10] |  |
| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` |  |
-| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` |  |
+| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
+| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` |  |
-**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-
-A single database query may involve multiple collections.
-
-If the collection name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single collection and it SHOULD match the value provided in
-the query text including any schema and database name prefix.
-
-For batch operations, if the individual operations are known to have the same collection name
-then that collection name SHOULD be used.
-
-If the operation or query involves multiple collections, `db.collection.name`
-SHOULD NOT be captured.
-
-This attribute has stability level RELEASE CANDIDATE.
-
-**[2] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
-
-**[3] `db.namespace`:** A connection's currently associated database may change during its lifetime, e.g. from executing `USE `.
+**[1] `db.namespace`:** A connection's currently associated database may change during its lifetime, e.g. from executing `USE `.
If instrumentation is unable to capture the connection's currently associated database on each query
without triggering an additional query to be executed (e.g. `SELECT DATABASE()`),
@@ -62,12 +42,7 @@ Instrumentation SHOULD document if `db.namespace` reflects the database provided
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-**[4] `db.operation.name`:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
-In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed.
-
-**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-
-**[6] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
+**[2] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
return code which is adopted by some database systems like PostgreSQL.
See [PostgreSQL error codes](https://www.postgresql.org/docs/current/errcodes-appendix.html)
for the details.
@@ -103,43 +78,41 @@ For example, generic DB instrumentation that detected an error and has
SQLSTATE `"42000"` and vendor-specific `1071` should set
`db.response.status_code` to `"42000/1071"`."
-**[7] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[3] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[9] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[5] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+**[7] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section.
This attribute has stability level RELEASE CANDIDATE.
-**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
+**[8] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
-**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[9] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
-**[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
-**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[11] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[16] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
+**[12] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`.
This attribute has stability level RELEASE CANDIDATE.
The following attributes can be important for making sampling decisions
and SHOULD be provided **at span creation time** (if provided at all):
-* [`db.collection.name`](/docs/attributes-registry/db.md)
* [`db.namespace`](/docs/attributes-registry/db.md)
-* [`db.operation.name`](/docs/attributes-registry/db.md)
* [`db.query.summary`](/docs/attributes-registry/db.md)
* [`db.query.text`](/docs/attributes-registry/db.md)
* [`server.address`](/docs/attributes-registry/server.md)
diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md
index cfba85f15f..842ae973e7 100644
--- a/docs/database/mongodb.md
+++ b/docs/database/mongodb.md
@@ -32,18 +32,12 @@ The Semantic Conventions for [MongoDB](https://www.mongodb.com/) extend and over
**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-A single database query may involve multiple collections.
-
-If the collection name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single collection and it SHOULD match the value provided in
-the query text including any schema and database name prefix.
+The collection name SHOULD NOT be extracted from `db.query.text`,
+unless the query format is known to only ever have a single collection name present.
For batch operations, if the individual operations are known to have the same collection name
then that collection name SHOULD be used.
-If the operation or query involves multiple collections, `db.collection.name`
-SHOULD NOT be captured.
-
This attribute has stability level RELEASE CANDIDATE.
**[2] `db.operation.name`:** See [MongoDB database commands](https://www.mongodb.com/docs/manual/reference/command/).
diff --git a/docs/database/mssql.md b/docs/database/mssql.md
index 0bb470dc9e..534ea341e5 100644
--- a/docs/database/mssql.md
+++ b/docs/database/mssql.md
@@ -21,38 +21,18 @@ The Semantic Conventions for the *Microsoft SQL Server* extend and override the
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of the SQL table that the operation is acting upon. [1] | `users`; `dbo.products` | `Conditionally Required` [2] |  |
-| [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection, qualified by the instance name. [3] | `instance1.products`; `customers` | `Conditionally Required` If available without an additional network call. |  |
-| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `SELECT`; `INSERT`; `UPDATE`; `DELETE`; `CREATE`; `mystoredproc` | `Conditionally Required` [5] |  |
-| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [Microsoft SQL Server error](https://learn.microsoft.com/sql/relational-databases/errors-events/database-engine-events-and-errors) number represented as a string. [6] | `102`; `40020` | `Conditionally Required` If response has ended with warning or an error. |  |
-| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [7] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. |  |
-| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [8] | `80`; `8080`; `443` | `Conditionally Required` [9] |  |
-| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [10] | `2`; `3`; `4` | `Recommended` |  |
-| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] |  |
-| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] |  |
+| [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection, qualified by the instance name. [1] | `instance1.products`; `customers` | `Conditionally Required` If available without an additional network call. |  |
+| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [Microsoft SQL Server error](https://learn.microsoft.com/sql/relational-databases/errors-events/database-engine-events-and-errors) number represented as a string. [2] | `102`; `40020` | `Conditionally Required` If response has ended with warning or an error. |  |
+| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. |  |
+| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` [5] |  |
+| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` |  |
+| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [8] |  |
+| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [10] |  |
| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` |  |
-| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` |  |
+| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
+| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` |  |
-**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-
-A single database query may involve multiple collections.
-
-If the collection name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single collection and it SHOULD match the value provided in
-the query text including any schema and database name prefix.
-
-For batch operations, if the individual operations are known to have the same collection name
-then that collection name SHOULD be used.
-
-If the operation or query involves multiple collections, `db.collection.name`
-SHOULD NOT be captured.
-
-This attribute has stability level RELEASE CANDIDATE.
-
-**[2] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
-
-**[3] `db.namespace`:** When connected to a default instance, `db.namespace` SHOULD be set to the name of
+**[1] `db.namespace`:** When connected to a default instance, `db.namespace` SHOULD be set to the name of
the database. When connected to a [named instance](https://learn.microsoft.com/sql/connect/jdbc/building-the-connection-url#named-and-multiple-sql-server-instances),
`db.namespace` SHOULD be set to the combination of instance and database name following the `{instance_name}.{database_name}` pattern.
@@ -66,50 +46,43 @@ Instrumentation SHOULD document if `db.namespace` reflects the database provided
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-**[4] `db.operation.name`:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
-In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed.
-
-**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-
-**[6] `db.response.status_code`:** Microsoft SQL Server does not report SQLSTATE.
+**[2] `db.response.status_code`:** Microsoft SQL Server does not report SQLSTATE.
-**[7] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[3] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[9] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[5] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+**[7] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section.
This attribute has stability level RELEASE CANDIDATE.
-**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
+**[8] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
-**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[9] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
-**[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
-**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[11] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[16] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
+**[12] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`.
This attribute has stability level RELEASE CANDIDATE.
The following attributes can be important for making sampling decisions
and SHOULD be provided **at span creation time** (if provided at all):
-* [`db.collection.name`](/docs/attributes-registry/db.md)
* [`db.namespace`](/docs/attributes-registry/db.md)
-* [`db.operation.name`](/docs/attributes-registry/db.md)
* [`db.query.summary`](/docs/attributes-registry/db.md)
* [`db.query.text`](/docs/attributes-registry/db.md)
* [`server.address`](/docs/attributes-registry/server.md)
diff --git a/docs/database/mysql.md b/docs/database/mysql.md
index 60b3d795f2..0e8ae0302b 100644
--- a/docs/database/mysql.md
+++ b/docs/database/mysql.md
@@ -21,38 +21,18 @@ The Semantic Conventions for *MySQL* extend and override the [Database Semantic
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of the SQL table that the operation is acting upon. [1] | `users`; `dbo.products` | `Conditionally Required` [2] |  |
-| [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection. [3] | `products`; `customers` | `Conditionally Required` If available without an additional network call. |  |
-| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `SELECT`; `INSERT`; `UPDATE`; `DELETE`; `CREATE`; `mystoredproc` | `Conditionally Required` [5] |  |
-| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html). [6] | `1005`; `MY-010016` | `Conditionally Required` If response has ended with warning or an error. |  |
-| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [7] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. |  |
-| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [8] | `80`; `8080`; `443` | `Conditionally Required` [9] |  |
-| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [10] | `2`; `3`; `4` | `Recommended` |  |
-| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] |  |
-| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] |  |
+| [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection. [1] | `products`; `customers` | `Conditionally Required` If available without an additional network call. |  |
+| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html). [2] | `1005`; `MY-010016` | `Conditionally Required` If response has ended with warning or an error. |  |
+| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. |  |
+| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` [5] |  |
+| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` |  |
+| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [8] |  |
+| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [10] |  |
| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` |  |
-| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` |  |
+| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
+| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` |  |
-**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-
-A single database query may involve multiple collections.
-
-If the collection name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single collection and it SHOULD match the value provided in
-the query text including any schema and database name prefix.
-
-For batch operations, if the individual operations are known to have the same collection name
-then that collection name SHOULD be used.
-
-If the operation or query involves multiple collections, `db.collection.name`
-SHOULD NOT be captured.
-
-This attribute has stability level RELEASE CANDIDATE.
-
-**[2] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
-
-**[3] `db.namespace`:** A connection's currently associated database may change during its lifetime, e.g. from executing `USE `.
+**[1] `db.namespace`:** A connection's currently associated database may change during its lifetime, e.g. from executing `USE `.
If instrumentation is unable to capture the connection's currently associated database on each query
without triggering an additional query to be executed (e.g. `SELECT DATABASE()`),
@@ -62,12 +42,7 @@ Instrumentation SHOULD document if `db.namespace` reflects the database provided
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-**[4] `db.operation.name`:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
-In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed.
-
-**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-
-**[6] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
+**[2] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
return code which is adopted by some database systems like PostgreSQL.
See [PostgreSQL error codes](https://www.postgresql.org/docs/current/errcodes-appendix.html)
for the details.
@@ -103,43 +78,41 @@ For example, generic DB instrumentation that detected an error and has
SQLSTATE `"42000"` and vendor-specific `1071` should set
`db.response.status_code` to `"42000/1071"`."
-**[7] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[3] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[9] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[5] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+**[7] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section.
This attribute has stability level RELEASE CANDIDATE.
-**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
+**[8] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
-**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[9] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
-**[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
-**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[11] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[16] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
+**[12] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`.
This attribute has stability level RELEASE CANDIDATE.
The following attributes can be important for making sampling decisions
and SHOULD be provided **at span creation time** (if provided at all):
-* [`db.collection.name`](/docs/attributes-registry/db.md)
* [`db.namespace`](/docs/attributes-registry/db.md)
-* [`db.operation.name`](/docs/attributes-registry/db.md)
* [`db.query.summary`](/docs/attributes-registry/db.md)
* [`db.query.text`](/docs/attributes-registry/db.md)
* [`server.address`](/docs/attributes-registry/server.md)
diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md
index 249e3a0481..30b132543a 100644
--- a/docs/database/postgresql.md
+++ b/docs/database/postgresql.md
@@ -21,38 +21,18 @@ The Semantic Conventions for *PostgreSQL* extend and override the [Database Sema
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of the SQL table that the operation is acting upon. [1] | `users`; `dbo.products` | `Conditionally Required` [2] |  |
-| [`db.namespace`](/docs/attributes-registry/db.md) | string | The schema associated with the connection, qualified by the database name. [3] | `mydatabase.products`; `mydatabase.customers` | `Conditionally Required` If available without an additional network call. |  |
-| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `SELECT`; `INSERT`; `UPDATE`; `DELETE`; `CREATE`; `mystoredproc` | `Conditionally Required` [5] |  |
-| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [PostgreSQL error code](https://www.postgresql.org/docs/current/errcodes-appendix.html). [6] | `08000`; `08P01` | `Conditionally Required` If response has ended with warning or an error. |  |
-| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [7] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. |  |
-| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [8] | `80`; `8080`; `443` | `Conditionally Required` [9] |  |
-| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [10] | `2`; `3`; `4` | `Recommended` |  |
-| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] |  |
-| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] |  |
+| [`db.namespace`](/docs/attributes-registry/db.md) | string | The schema associated with the connection, qualified by the database name. [1] | `mydatabase.products`; `mydatabase.customers` | `Conditionally Required` If available without an additional network call. |  |
+| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [PostgreSQL error code](https://www.postgresql.org/docs/current/errcodes-appendix.html). [2] | `08000`; `08P01` | `Conditionally Required` If response has ended with warning or an error. |  |
+| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. |  |
+| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` [5] |  |
+| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` |  |
+| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [8] |  |
+| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [10] |  |
| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` |  |
-| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` |  |
+| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
+| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` |  |
-**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-
-A single database query may involve multiple collections.
-
-If the collection name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single collection and it SHOULD match the value provided in
-the query text including any schema and database name prefix.
-
-For batch operations, if the individual operations are known to have the same collection name
-then that collection name SHOULD be used.
-
-If the operation or query involves multiple collections, `db.collection.name`
-SHOULD NOT be captured.
-
-This attribute has stability level RELEASE CANDIDATE.
-
-**[2] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
-
-**[3] `db.namespace`:** `db.namespace` SHOULD be set to the combination of database and schema name following the `{database}.{schema}` pattern.
+**[1] `db.namespace`:** `db.namespace` SHOULD be set to the combination of database and schema name following the `{database}.{schema}` pattern.
A connection's currently associated database may change during its lifetime, e.g. from executing `SET search_path TO `.
If the search path has multiple schemas, the first schema in the search path SHOULD be used.
@@ -69,12 +49,7 @@ Instrumentation SHOULD document if `db.namespace` reflects the user provided whe
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-**[4] `db.operation.name`:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
-In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed.
-
-**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-
-**[6] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
+**[2] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
return code which is adopted by some database systems like PostgreSQL.
See [PostgreSQL error codes](https://www.postgresql.org/docs/current/errcodes-appendix.html)
for the details.
@@ -110,43 +85,41 @@ For example, generic DB instrumentation that detected an error and has
SQLSTATE `"42000"` and vendor-specific `1071` should set
`db.response.status_code` to `"42000/1071"`."
-**[7] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[3] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[9] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[5] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+**[7] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section.
This attribute has stability level RELEASE CANDIDATE.
-**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
+**[8] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
-**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[9] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
-**[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
-**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[11] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[16] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
+**[12] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`.
This attribute has stability level RELEASE CANDIDATE.
The following attributes can be important for making sampling decisions
and SHOULD be provided **at span creation time** (if provided at all):
-* [`db.collection.name`](/docs/attributes-registry/db.md)
* [`db.namespace`](/docs/attributes-registry/db.md)
-* [`db.operation.name`](/docs/attributes-registry/db.md)
* [`db.query.summary`](/docs/attributes-registry/db.md)
* [`db.query.text`](/docs/attributes-registry/db.md)
* [`server.address`](/docs/attributes-registry/server.md)
diff --git a/docs/database/redis.md b/docs/database/redis.md
index a7b111bc4e..35c5b186a3 100644
--- a/docs/database/redis.md
+++ b/docs/database/redis.md
@@ -50,10 +50,8 @@ Instrumentation SHOULD document if `db.namespace` reflects the database index pr
**[2] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization.
-A single database query may involve multiple operations. If the operation
-name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single operation or when the operation name describing the
-whole query is available by other means.
+The operation name SHOULD NOT be extracted from `db.query.text`,
+unless the query format is known to only ever have a single operation name present.
For batch operations, if the individual operations are known to have the same operation name
then that operation name SHOULD be used prepended by `BATCH `,
diff --git a/docs/database/sql.md b/docs/database/sql.md
index 92df4eef51..3e43150ab4 100644
--- a/docs/database/sql.md
+++ b/docs/database/sql.md
@@ -45,38 +45,18 @@ Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic co
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of the SQL table that the operation is acting upon. [1] | `users`; `dbo.products` | `Conditionally Required` [2] |  |
-| [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection, fully qualified within the server address and port. [3] | `customers`; `test.users` | `Conditionally Required` If available without an additional network call. |  |
-| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `SELECT`; `INSERT`; `UPDATE`; `DELETE`; `CREATE`; `mystoredproc` | `Conditionally Required` [5] |  |
-| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response code recorded as string. [6] | `ORA-17027`; `1052`; `2201B` | `Conditionally Required` If response has ended with warning or an error. |  |
-| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [7] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. |  |
-| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [8] | `80`; `8080`; `443` | `Conditionally Required` [9] |  |
-| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [10] | `2`; `3`; `4` | `Recommended` |  |
-| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] |  |
-| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] |  |
+| [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection, fully qualified within the server address and port. [1] | `customers`; `test.users` | `Conditionally Required` If available without an additional network call. |  |
+| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response code recorded as string. [2] | `ORA-17027`; `1052`; `2201B` | `Conditionally Required` If response has ended with warning or an error. |  |
+| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. |  |
+| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` [5] |  |
+| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` |  |
+| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [8] |  |
+| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [10] |  |
| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` |  |
-| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
-| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` |  |
+| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
+| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` |  |
-**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-
-A single database query may involve multiple collections.
-
-If the collection name is parsed from the query text, it SHOULD only be captured for queries that
-contain a single collection and it SHOULD match the value provided in
-the query text including any schema and database name prefix.
-
-For batch operations, if the individual operations are known to have the same collection name
-then that collection name SHOULD be used.
-
-If the operation or query involves multiple collections, `db.collection.name`
-SHOULD NOT be captured.
-
-This attribute has stability level RELEASE CANDIDATE.
-
-**[2] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
-
-**[3] `db.namespace`:** If a database system has multiple namespace components (e.g. schema name and database name), they SHOULD be concatenated
+**[1] `db.namespace`:** If a database system has multiple namespace components (e.g. schema name and database name), they SHOULD be concatenated
(potentially using database system specific conventions) from most general to most
specific namespace component, and more specific namespaces SHOULD NOT be captured without
the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
@@ -94,12 +74,7 @@ Instrumentation SHOULD document if `db.namespace` reflects the database provided
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
-**[4] `db.operation.name`:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
-In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed.
-
-**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
-
-**[6] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
+**[2] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database
return code which is adopted by some database systems like PostgreSQL.
See [PostgreSQL error codes](https://www.postgresql.org/docs/current/errcodes-appendix.html)
for the details.
@@ -135,42 +110,40 @@ For example, generic DB instrumentation that detected an error and has
SQLSTATE `"42000"` and vendor-specific `1071` should set
`db.response.status_code` to `"42000/1071"`."
-**[7] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+**[3] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
Instrumentations SHOULD document how `error.type` is populated.
-**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[9] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
+**[5] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
-**[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+**[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
This attribute has stability level RELEASE CANDIDATE.
-**[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
+**[7] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.
Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section.
This attribute has stability level RELEASE CANDIDATE.
-**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
+**[8] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
-**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[9] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
This attribute has stability level RELEASE CANDIDATE.
-**[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+**[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
-**[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[11] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
-**[16] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
+**[12] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index.
If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`.
This attribute has stability level RELEASE CANDIDATE.
The following attributes can be important for making sampling decisions
and SHOULD be provided **at span creation time** (if provided at all):
-* [`db.collection.name`](/docs/attributes-registry/db.md)
-* [`db.operation.name`](/docs/attributes-registry/db.md)
* [`db.query.summary`](/docs/attributes-registry/db.md)
* [`db.query.text`](/docs/attributes-registry/db.md)
* [`server.address`](/docs/attributes-registry/server.md)
@@ -196,12 +169,10 @@ This is an example of attributes for a MySQL database span:
| Key | Value |
|:-----------------------| :----------------------------------------------------------- |
| Span name | `"SELECT orders"` |
-| `db.collection.name` | `"orders"` |
| `db.namespace` | `"ShopDb"` |
| `db.system` | `"mysql"` |
| `server.address` | `"shopdb.example.com"` |
| `server.port` | `3306` |
| `db.query.text` | `"SELECT * FROM orders WHERE order_id = 'o4711'"` |
-| `db.operation.name` | `"SELECT"` |
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/model/database/common.yaml b/model/database/common.yaml
index 27d0817220..7cb4429964 100644
--- a/model/database/common.yaml
+++ b/model/database/common.yaml
@@ -4,12 +4,6 @@ groups:
brief: 'Database Client attributes'
stability: experimental
attributes:
- - ref: db.operation.name
- requirement_level:
- conditionally_required: >
- If readily available and if there is a single operation name that describes the
- database call. The operation name MAY be parsed from the query text,
- in which case it SHOULD be the single operation name found in the query.
- ref: server.address
brief: >
Name of the database host.
@@ -42,13 +36,16 @@ groups:
# - ref: db.system
# requirement_level:
# conditionally_required: if available
+ - ref: db.operation.name
+ requirement_level: # TODO (trask) simplify
+ conditionally_required: >
+ If readily available and if there is a single operation name that describes the
+ database call. The operation name MAY be parsed from the query text,
+ in which case it SHOULD be the single operation name found in the query.
- ref: db.collection.name
- brief: >
- Cosmos DB container name.
- note: >
- It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
+ brief: Cosmos DB container name.
requirement_level:
- conditionally_required: If available
+ conditionally_required: If available.
- ref: db.namespace
requirement_level:
conditionally_required: If available.
@@ -60,19 +57,33 @@ groups:
requirement_level:
conditionally_required: If available.
- - id: attributes.db.client.with_query_and_collection
+ - id: attributes.db.client.with_query
extends: attributes.db.client.minimal
type: attribute_group
stability: experimental
brief: This group defines the attributes describing database operations that
- have query and collection name.
+ may have queries.
attributes:
- ref: db.query.text
- ref: db.query.summary
requirement_level:
recommended: if readily available or if instrumentation supports query summarization.
+
+ - id: attributes.db.client.with_query_and_collection
+ extends: attributes.db.client.with_query
+ type: attribute_group
+ stability: experimental
+ brief: This group defines the attributes describing database operations that
+ have operation name, collection name and query.
+ attributes:
+ - ref: db.operation.name
+ requirement_level: # TODO (trask) simplify
+ conditionally_required: >
+ If readily available and if there is a single operation name that describes the
+ database call. The operation name MAY be parsed from the query text,
+ in which case it SHOULD be the single operation name found in the query.
- ref: db.collection.name
- requirement_level:
+ requirement_level: # TODO (trask) simplify
conditionally_required: >
If readily available and if a database call is performed on a single collection.
The collection name MAY be parsed from the query text,
diff --git a/model/database/registry.yaml b/model/database/registry.yaml
index f93fa98fbb..6b731a9603 100644
--- a/model/database/registry.yaml
+++ b/model/database/registry.yaml
@@ -12,18 +12,12 @@ groups:
note: |
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
- A single database query may involve multiple collections.
-
- If the collection name is parsed from the query text, it SHOULD only be captured for queries that
- contain a single collection and it SHOULD match the value provided in
- the query text including any schema and database name prefix.
+ The collection name SHOULD NOT be extracted from `db.query.text`,
+ unless the query format is known to only ever have a single collection name present.
For batch operations, if the individual operations are known to have the same collection name
then that collection name SHOULD be used.
- If the operation or query involves multiple collections, `db.collection.name`
- SHOULD NOT be captured.
-
This attribute has stability level RELEASE CANDIDATE.
examples: ["public.users", "customers"]
- id: db.namespace
@@ -53,10 +47,8 @@ groups:
It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization.
- A single database query may involve multiple operations. If the operation
- name is parsed from the query text, it SHOULD only be captured for queries that
- contain a single operation or when the operation name describing the
- whole query is available by other means.
+ The operation name SHOULD NOT be extracted from `db.query.text`,
+ unless the query format is known to only ever have a single operation name present.
For batch operations, if the individual operations are known to have the same operation name
then that operation name SHOULD be used prepended by `BATCH `,
diff --git a/model/database/spans.yaml b/model/database/spans.yaml
index 8a5d087d7c..30ec2fe1e0 100644
--- a/model/database/spans.yaml
+++ b/model/database/spans.yaml
@@ -10,18 +10,29 @@ groups:
# sampling_relevant: true
- ref: db.operation.name
sampling_relevant: true
+ requirement_level: # TODO (trask) simplify
+ conditionally_required: >
+ If readily available and if there is a single operation name that describes the
+ database call. The operation name MAY be parsed from the query text,
+ in which case it SHOULD be the single operation name found in the query.
- ref: db.operation.batch.size
- ref: server.address
sampling_relevant: true
- ref: server.port
sampling_relevant: true
- - id: trace.db.common.query_and_collection
- extends: attributes.db.client.with_query_and_collection
+ - id: trace.db.common.query
+ extends: attributes.db.client.with_query
type: attribute_group
stability: experimental
brief: This group defines the attributes used to perform database client calls.
attributes:
+ - ref: server.address
+ sampling_relevant: true
+ - ref: server.port
+ sampling_relevant: true
+ - ref: db.operation.batch.size
+ - ref: db.response.returned_rows
- ref: db.query.text
sampling_relevant: true
requirement_level:
@@ -37,6 +48,13 @@ groups:
sampling_relevant: true
- ref: db.operation.parameter
requirement_level: opt_in
+
+ - id: trace.db.common.query_and_collection
+ extends: attributes.db.client.with_query_and_collection
+ type: attribute_group
+ stability: experimental
+ brief: This group defines the attributes used to perform database client calls.
+ attributes:
- ref: db.collection.name
sampling_relevant: true
- ref: db.operation.name
@@ -47,6 +65,21 @@ groups:
- ref: server.port
sampling_relevant: true
- ref: db.response.returned_rows
+ - ref: db.query.text
+ sampling_relevant: true
+ requirement_level:
+ recommended: >
+ Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes
+ sensitive data, e.g. by redacting all literal values present in the query text.
+ See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext).
+
+ Parameterized query text SHOULD be collected by default
+ (the query parameter values themselves are opt-in,
+ see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)).
+ - ref: db.query.summary
+ sampling_relevant: true
+ - ref: db.operation.parameter
+ requirement_level: opt_in
- id: trace.db.common.full
type: attribute_group
@@ -307,7 +340,7 @@ groups:
type: span
stability: experimental
span_kind: client
- extends: attributes.db.client.minimal
+ extends: trace.db.common.minimal
brief: >
Attributes for Redis
attributes:
@@ -462,19 +495,10 @@ groups:
type: span
span_kind: client
stability: experimental
- extends: trace.db.common.query_and_collection
+ extends: trace.db.common.query
brief: >
Attributes for SQL databases
attributes:
- - ref: db.operation.name
- note: >
- This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.
-
- In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed.
- examples: ['SELECT', 'INSERT', 'UPDATE', 'DELETE', 'CREATE', 'mystoredproc']
- - ref: db.collection.name
- brief: The name of the SQL table that the operation is acting upon.
- examples: ['users', 'dbo.products']
- ref: db.namespace
brief: >
The database associated with the connection,
From a6dfa97a93c512f5315aa021fc2d6cfcf5c79f0f Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 25 Nov 2024 18:50:46 -0800
Subject: [PATCH 16/32] Bump markdownlint-cli from 0.42.0 to 0.43.0 (#1611)
Signed-off-by: dependabot[bot]
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
package.json | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/package.json b/package.json
index acfdd4bad4..ef069a000a 100644
--- a/package.json
+++ b/package.json
@@ -14,7 +14,7 @@
"markdown-link-check": "3.11.2",
"markdown-toc": "^1.2.0",
"markdownlint": "0.36.1",
- "markdownlint-cli": "0.42.0",
+ "markdownlint-cli": "0.43.0",
"prettier": "^3.0.0",
"through2": "^4.0.2"
},
From 7c76c20e4f2fe502bc1b802e97bf8b53415168f1 Mon Sep 17 00:00:00 2001
From: Liudmila Molkova
Date: Tue, 26 Nov 2024 09:04:32 -0800
Subject: [PATCH 17/32] Add Daniel Dyla to SemConv approvers (#1615)
Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com>
---
README.md | 1 +
1 file changed, 1 insertion(+)
diff --git a/README.md b/README.md
index 6227be7ca2..e81f0e5698 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,7 @@ Approvers ([@open-telemetry/specs-semconv-approvers](https://github.com/orgs/ope
- [Alexandra Konrad](https://github.com/trisch-me), Elastic
- [Christian Neumüller](https://github.com/Oberon00), Dynatrace
+- [Daniel Dyla](https://github.com/dyladan), Dynatrace
- [James Moessis](https://github.com/jamesmoessis), Atlassian
- [Sean Marciniak](https://github.com/MovieStoreGuy), Atlassian
- [Ted Young](https://github.com/tedsuo), Lightstep
From aca6d57d6a72b9e5ba7c19ab941c8a07d0e343b1 Mon Sep 17 00:00:00 2001
From: Jamie Danielson
Date: Tue, 26 Nov 2024 12:31:50 -0500
Subject: [PATCH 18/32] Fix typo in schemas for messaging attribute changes
(#1595)
---
.chloggen/fix-typo-messaging-schema.yaml | 4 ++++
schema-next.yaml | 4 ++--
2 files changed, 6 insertions(+), 2 deletions(-)
create mode 100644 .chloggen/fix-typo-messaging-schema.yaml
diff --git a/.chloggen/fix-typo-messaging-schema.yaml b/.chloggen/fix-typo-messaging-schema.yaml
new file mode 100644
index 0000000000..c487a03f06
--- /dev/null
+++ b/.chloggen/fix-typo-messaging-schema.yaml
@@ -0,0 +1,4 @@
+change_type: 'bug_fix'
+component: messaging
+note: Fix typo in schemas for messaging attribute changes
+issues: [1595]
diff --git a/schema-next.yaml b/schema-next.yaml
index 50afab2b96..de73f27640 100644
--- a/schema-next.yaml
+++ b/schema-next.yaml
@@ -59,8 +59,8 @@ versions:
attribute_map:
messaging.kafka.consumer.group: messaging.consumer.group.name
messaging.rocketmq.client_group: messaging.consumer.group.name
- messaging.evenhubs.consumer.group: messaging.consumer.group.name
- message.servicebus.destination.subscription_name: messaging.destination.subscription.name
+ messaging.eventhubs.consumer.group: messaging.consumer.group.name
+ messaging.servicebus.destination.subscription_name: messaging.destination.subscription.name
# https://github.com/open-telemetry/semantic-conventions/pull/1200
- rename_attributes:
attribute_map:
From f49b5cd076ffa761759c0ea02c2a6fc81ccf0a4a Mon Sep 17 00:00:00 2001
From: Liudmila Molkova
Date: Tue, 26 Nov 2024 12:50:34 -0800
Subject: [PATCH 19/32] Add section on span status for databases (#1560)
Co-authored-by: Trask Stalnaker
---
.chloggen/1560.yaml | 4 +++
docs/database/database-spans.md | 60 +++++++++++++++++++++++++++++++++
2 files changed, 64 insertions(+)
create mode 100644 .chloggen/1560.yaml
diff --git a/.chloggen/1560.yaml b/.chloggen/1560.yaml
new file mode 100644
index 0000000000..35769898b7
--- /dev/null
+++ b/.chloggen/1560.yaml
@@ -0,0 +1,4 @@
+change_type: enhancement
+component: db
+note: Specify how to set span status for database operations.
+issues: [1536, 1560]
diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md
index 597a9de6cf..bf5dc93347 100644
--- a/docs/database/database-spans.md
+++ b/docs/database/database-spans.md
@@ -11,6 +11,8 @@ linkTitle: Client Calls
- [Name](#name)
+- [Status](#status)
+ - [Recording exception events](#recording-exception-events)
- [Common attributes](#common-attributes)
- [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem)
- [Sanitization of `db.query.text`](#sanitization-of-dbquerytext)
@@ -85,6 +87,62 @@ and SHOULD adhere to one of the following values, provided they are accessible:
If a corresponding `{target}` value is not available for a specific operation, the instrumentation SHOULD omit the `{target}`.
For example, for an operation describing SQL query on an anonymous table like `SELECT * FROM (SELECT * FROM table) t`, span name should be `SELECT`.
+## Status
+
+[Span Status Code][SpanStatus] MUST be left unset if the operation has ended without any errors.
+
+Instrumentation SHOULD consider the operation as failed if any of the following is true:
+
+- the `db.response.status_code` value indicates an error
+
+ > [!NOTE]
+ >
+ > The classification of status code as an error depends on the context.
+ > For example, a SQL STATE `02000` (`no_data`) indicates an error when the application
+ > expected the data to be available. However, it is not an error when the
+ > application is simply checking whether the data exists.
+ >
+ > Instrumentations that have additional context about a specific operation MAY use
+ > this context to set the span status more precisely.
+ > Instrumentations that don't have any additional context MUST follow the
+ > guidelines in this section.
+
+- an exception is thrown by the instrumented method call
+- the instrumented method returns an error in another way
+
+When the operation ends with an error, instrumentation:
+
+- SHOULD set the span status code to `Error`
+- SHOULD set the `error.type` attribute
+- SHOULD set the span status description when it has additional information
+ about the error which is not expected to contain sensitive details and aligns
+ with [Span Status Description][SpanStatus] definition.
+
+ It's NOT RECOMMENDED to duplicate `db.response.status_code` or `error.type`
+ in span status description.
+
+ When the operation fails with an exception, the span status description SHOULD be set to
+ the exception message.
+
+### Recording exception events
+
+**Status**: [Experimental][DocumentStatus]
+
+When the operation fails with an exception, instrumentation SHOULD record
+an [exception event](../exceptions/exceptions-spans.md) by default if, and only if,
+the span being recorded is a local root span (does not have a local parent).
+
+> [!NOTE]
+>
+> Exception stack traces could be very long and are expensive to capture and store.
+> Exceptions which are not handled by instrumented libraries are likely to be handled
+> and logged by the caller.
+> Exceptions that are not handled will be recorded by the outermost (local root)
+> instrumentation such as HTTP or gRPC server.
+
+Instrumentation MAY provide a configuration option to record exceptions that
+escape the surface of the instrumented API.
+
## Common attributes
These attributes will usually be the same for all operations performed over the same database connection.
@@ -309,6 +367,7 @@ The `db.query.summary` attribute captures a shortened representation of a query
which SHOULD have low-cardinality and SHOULD NOT contain any dynamic or sensitive data.
> [!NOTE]
+>
> The `db.query.text` attribute is intended to identify individual queries. Even though
> it is sanitized if captured by default, it could still have high cardinality and
> might reach hundreds of lines.
@@ -418,3 +477,4 @@ More specific Semantic Conventions are defined for the following database techno
* [SQL](sql.md): Semantic Conventions for *SQL* databases.
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
+[SpanStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/trace/api.md#set-status
From 3357f693776002e1df800b738f91075da2d4a98b Mon Sep 17 00:00:00 2001
From: Riccardo Magliocchetti
Date: Tue, 26 Nov 2024 22:09:20 +0100
Subject: [PATCH 20/32] Add conventions for CLI Spans (#1588)
Co-authored-by: Liudmila Molkova
---
.chloggen/add-cli-spans.yaml | 22 +++++++
docs/cli/cli-spans.md | 122 +++++++++++++++++++++++++++++++++++
model/cli/spans.yaml | 42 ++++++++++++
3 files changed, 186 insertions(+)
create mode 100644 .chloggen/add-cli-spans.yaml
create mode 100644 docs/cli/cli-spans.md
create mode 100644 model/cli/spans.yaml
diff --git a/.chloggen/add-cli-spans.yaml b/.chloggen/add-cli-spans.yaml
new file mode 100644
index 0000000000..428bb1d701
--- /dev/null
+++ b/.chloggen/add-cli-spans.yaml
@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: 'new_component'
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: 'cli'
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Define span describing CLI application execution
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1577]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/docs/cli/cli-spans.md b/docs/cli/cli-spans.md
new file mode 100644
index 0000000000..be7e2a61b8
--- /dev/null
+++ b/docs/cli/cli-spans.md
@@ -0,0 +1,122 @@
+
+
+# Semantic Conventions for CLI (Command Line Interface) programs
+
+**Status**: [Experimental][DocumentStatus]
+
+This document defines semantic conventions to apply when instrumenting CLI programs, both as a caller and as callee. This document is intended for short-lived programs that end their execution, i.e. not daemon or long running background tasks.
+
+Span kind SHOULD be `INTERNAL` when the traced program is the callee or `CLIENT` when the caller is tracing another program.
+
+The span name SHOULD be set to `{process.executable.name}`.
+Instrumentations that have additional context about executed commands MAY use a different low-cardinality span name format and SHOULD document it.
+
+Span status SHOULD be set to `Error` if `{process.exit.code}` is not 0.
+
+
+
+## Execution (callee) spans
+
+
+
+
+
+
+
+
+| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`process.executable.name`](/docs/attributes-registry/process.md) | string | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | `Required` |  |
+| [`process.exit.code`](/docs/attributes-registry/process.md) | int | The exit code of the process. | `127` | `Required` |  |
+| [`process.pid`](/docs/attributes-registry/process.md) | int | Process identifier (PID). | `1234` | `Required` |  |
+| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if and only if process.exit.code is not 0 |  |
+| [`process.command_args`](/docs/attributes-registry/process.md) | string[] | All the command arguments (including the command/executable itself) as received by the process. On Linux-based systems (and some other Unixoid systems supporting procfs), can be set according to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. For libc-based executables, this would be the full argv vector passed to `main`. | `["cmd/otecol", "--config=config.yaml"]` | `Recommended` |  |
+| [`process.executable.path`](/docs/attributes-registry/process.md) | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | `Recommended` |  |
+
+**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
+
+When `error.type` is set to a type (e.g., an exception type), its
+canonical class name identifying the type within the artifact SHOULD be used.
+
+Instrumentations SHOULD document the list of errors they report.
+
+The cardinality of `error.type` within one instrumentation library SHOULD be low.
+Telemetry consumers that aggregate data from multiple instrumentation libraries and applications
+should be prepared for `error.type` to have high cardinality at query time when no
+additional filters are applied.
+
+If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`.
+
+If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes),
+it's RECOMMENDED to:
+
+- Use a domain-specific attribute
+- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
+
+---
+
+`error.type` 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.
+
+| Value | Description | Stability |
+|---|---|---|
+| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+
+
+
+
+
+
+## Client (caller) spans
+
+
+
+
+
+
+
+
+| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`process.executable.name`](/docs/attributes-registry/process.md) | string | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | `Required` |  |
+| [`process.exit.code`](/docs/attributes-registry/process.md) | int | The exit code of the process. | `127` | `Required` |  |
+| [`process.pid`](/docs/attributes-registry/process.md) | int | Process identifier (PID). | `1234` | `Required` |  |
+| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if and only if process.exit.code is not 0 |  |
+| [`process.command_args`](/docs/attributes-registry/process.md) | string[] | All the command arguments (including the command/executable itself) as received by the process. On Linux-based systems (and some other Unixoid systems supporting procfs), can be set according to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. For libc-based executables, this would be the full argv vector passed to `main`. | `["cmd/otecol", "--config=config.yaml"]` | `Recommended` |  |
+| [`process.executable.path`](/docs/attributes-registry/process.md) | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | `Recommended` |  |
+
+**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
+
+When `error.type` is set to a type (e.g., an exception type), its
+canonical class name identifying the type within the artifact SHOULD be used.
+
+Instrumentations SHOULD document the list of errors they report.
+
+The cardinality of `error.type` within one instrumentation library SHOULD be low.
+Telemetry consumers that aggregate data from multiple instrumentation libraries and applications
+should be prepared for `error.type` to have high cardinality at query time when no
+additional filters are applied.
+
+If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`.
+
+If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes),
+it's RECOMMENDED to:
+
+- Use a domain-specific attribute
+- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
+
+---
+
+`error.type` 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.
+
+| Value | Description | Stability |
+|---|---|---|
+| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+
+
+
+
+
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/model/cli/spans.yaml b/model/cli/spans.yaml
new file mode 100644
index 0000000000..4df8e9c32f
--- /dev/null
+++ b/model/cli/spans.yaml
@@ -0,0 +1,42 @@
+groups:
+ - id: span.cli.internal
+ type: span
+ span_kind: internal
+ stability: experimental
+ brief: >
+ Describes span of CLI (Command Line Interfaces) programs.
+ attributes:
+ - ref: process.executable.name
+ requirement_level: required
+ - ref: process.executable.path
+ requirement_level: recommended
+ - ref: process.pid
+ requirement_level: required
+ - ref: process.exit.code
+ requirement_level: required
+ - ref: process.command_args
+ requirement_level: recommended
+ - ref: error.type
+ requirement_level:
+ conditionally_required: if and only if process.exit.code is not 0
+
+ - id: span.cli.client
+ type: span
+ span_kind: client
+ stability: experimental
+ brief: >
+ Describes span to calls of CLI (Command Line Interfaces) programs.
+ attributes:
+ - ref: process.executable.name
+ requirement_level: required
+ - ref: process.executable.path
+ requirement_level: recommended
+ - ref: process.pid
+ requirement_level: required
+ - ref: process.exit.code
+ requirement_level: required
+ - ref: process.command_args
+ requirement_level: recommended
+ - ref: error.type
+ requirement_level:
+ conditionally_required: if and only if process.exit.code is not 0
From 68629b9f7e1696e4030b0acd4535eddc02328b7e Mon Sep 17 00:00:00 2001
From: Christos Markou
Date: Tue, 26 Nov 2024 23:27:00 +0200
Subject: [PATCH 21/32] Add uptime metrics for container, k8s Pod and k8s Node
(#1617)
Signed-off-by: ChrsMark
Co-authored-by: Liudmila Molkova
---
.chloggen/add_k8s_uptime_metrics.yaml | 22 +++++++++++++
docs/system/container-metrics.md | 24 ++++++++++++++
docs/system/k8s-metrics.md | 46 +++++++++++++++++++++++++++
model/container/metrics.yaml | 11 +++++++
model/k8s/metrics.yaml | 22 +++++++++++++
5 files changed, 125 insertions(+)
create mode 100755 .chloggen/add_k8s_uptime_metrics.yaml
diff --git a/.chloggen/add_k8s_uptime_metrics.yaml b/.chloggen/add_k8s_uptime_metrics.yaml
new file mode 100755
index 0000000000..b0507f1d2b
--- /dev/null
+++ b/.chloggen/add_k8s_uptime_metrics.yaml
@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: k8s
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add uptime metrics for container, K8s Pod and K8s Node
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1486]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/docs/system/container-metrics.md b/docs/system/container-metrics.md
index 8d7faa892c..11f046c837 100644
--- a/docs/system/container-metrics.md
+++ b/docs/system/container-metrics.md
@@ -12,6 +12,29 @@ This document describes instruments and attributes for common container level
metrics in OpenTelemetry. These metrics are collected from technology-specific,
well-defined APIs (e.g. Kubelet's API or container runtimes).
+### Metric: `container.uptime`
+
+This metric is [recommended][MetricRecommended].
+
+
+
+
+
+
+
+
+| Name | Instrument Type | Unit (UCUM) | Description | Stability |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `container.uptime` | Gauge | `s` | The time the container has been running [1] |  |
+
+**[1]:** Instrumentations SHOULD use a gauge with type `double` and measure uptime in seconds as a floating point number with the highest precision available.
+The actual accuracy would depend on the instrumentation and operating system.
+
+
+
+
+
+
### Metric: `container.cpu.time`
This metric is [opt-in][MetricOptIn].
@@ -198,3 +221,4 @@ This metric is [opt-in][MetricOptIn].
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
[MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in
+[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
diff --git a/docs/system/k8s-metrics.md b/docs/system/k8s-metrics.md
index a94eac4050..9187ddf2db 100644
--- a/docs/system/k8s-metrics.md
+++ b/docs/system/k8s-metrics.md
@@ -15,6 +15,29 @@ well-defined APIs (e.g. Kubelet's API).
Metrics in `k8s.` instruments SHOULD be attached to a [K8s Resource](/docs/resource/k8s.md)
and therefore inherit its attributes, like `k8s.pod.name` and `k8s.pod.uid`.
+### Metric: `k8s.pod.uptime`
+
+This metric is [recommended][MetricRecommended].
+
+
+
+
+
+
+
+
+| Name | Instrument Type | Unit (UCUM) | Description | Stability |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `k8s.pod.uptime` | Gauge | `s` | The time the Pod has been running [1] |  |
+
+**[1]:** Instrumentations SHOULD use a gauge with type `double` and measure uptime in seconds as a floating point number with the highest precision available.
+The actual accuracy would depend on the instrumentation and operating system.
+
+
+
+
+
+
### Metric: `k8s.pod.cpu.time`
This metric is [recommended][MetricRecommended].
@@ -149,6 +172,29 @@ This metric is [recommended][MetricRecommended].
+### Metric: `k8s.node.uptime`
+
+This metric is [recommended][MetricRecommended].
+
+
+
+
+
+
+
+
+| Name | Instrument Type | Unit (UCUM) | Description | Stability |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `k8s.node.uptime` | Gauge | `s` | The time the Node has been running [1] |  |
+
+**[1]:** Instrumentations SHOULD use a gauge with type `double` and measure uptime in seconds as a floating point number with the highest precision available.
+The actual accuracy would depend on the instrumentation and operating system.
+
+
+
+
+
+
### Metric: `k8s.node.cpu.time`
This metric is [recommended][MetricRecommended].
diff --git a/model/container/metrics.yaml b/model/container/metrics.yaml
index d59d6845fd..a1af10deff 100644
--- a/model/container/metrics.yaml
+++ b/model/container/metrics.yaml
@@ -1,4 +1,15 @@
groups:
+ # container.* metrics
+ - id: metric.container.uptime
+ type: metric
+ metric_name: container.uptime
+ stability: experimental
+ brief: "The time the container has been running"
+ note: |
+ Instrumentations SHOULD use a gauge with type `double` and measure uptime in seconds as a floating point number with the highest precision available.
+ The actual accuracy would depend on the instrumentation and operating system.
+ instrument: gauge
+ unit: "s"
# container.cpu.* metrics and attribute group
- id: metric.container.cpu.time
type: metric
diff --git a/model/k8s/metrics.yaml b/model/k8s/metrics.yaml
index 2e59cef71e..7afd7ec20d 100644
--- a/model/k8s/metrics.yaml
+++ b/model/k8s/metrics.yaml
@@ -1,4 +1,15 @@
groups:
+ # k8s.pod.* metrics
+ - id: metric.k8s.pod.uptime
+ type: metric
+ metric_name: k8s.pod.uptime
+ stability: experimental
+ brief: "The time the Pod has been running"
+ note: |
+ Instrumentations SHOULD use a gauge with type `double` and measure uptime in seconds as a floating point number with the highest precision available.
+ The actual accuracy would depend on the instrumentation and operating system.
+ instrument: gauge
+ unit: "s"
# k8s.pod.cpu.* metrics
- id: metric.k8s.pod.cpu.time
type: metric
@@ -52,6 +63,17 @@ groups:
- ref: network.interface.name
- ref: network.io.direction
+ # k8s.node.* metrics
+ - id: metric.k8s.node.uptime
+ type: metric
+ metric_name: k8s.node.uptime
+ stability: experimental
+ brief: "The time the Node has been running"
+ note: |
+ Instrumentations SHOULD use a gauge with type `double` and measure uptime in seconds as a floating point number with the highest precision available.
+ The actual accuracy would depend on the instrumentation and operating system.
+ instrument: gauge
+ unit: "s"
# k8s.node.cpu.* metrics
- id: metric.k8s.node.cpu.time
type: metric
From 023f00db8b683fd4a0fd6185b303022e5025dbcb Mon Sep 17 00:00:00 2001
From: Braydon Kains <93549768+braydonk@users.noreply.github.com>
Date: Wed, 27 Nov 2024 11:25:46 -0500
Subject: [PATCH 22/32] [chore] update codeowners with additional system
semconv sections (#1623)
---
.github/CODEOWNERS | 10 +++++++---
1 file changed, 7 insertions(+), 3 deletions(-)
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index af09caa17e..5c2a3334df 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -36,17 +36,21 @@
/model/http/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
/model/error/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
/model/client/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
-/model/network/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers @open-telemetry/semconv-security-approvers
+/model/network/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers @open-telemetry/semconv-system-approvers @open-telemetry/semconv-security-approvers
/model/server/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
/model/url/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
/model/user-agent/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
# System semantic conventions
/docs/process/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers @open-telemetry/semconv-security-approvers
-/docs/system/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
/docs/resource/host.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
+/docs/resource/process.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
+/docs/system/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
+/model/disk/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
/model/host/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
-/model/process/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers @open-telemetry/semconv-security-approvers
+# /model/network/ is defined in HTTP section
+/model/os/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
+/model/process/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers @open-telemetry/semconv-security-approvers
/model/system/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
# Mobile semantic conventions
From 0c17ad55433353d50b68c240743a74b1332f47cf Mon Sep 17 00:00:00 2001
From: Trent Mick
Date: Wed, 27 Nov 2024 10:10:24 -0800
Subject: [PATCH 23/32] GenAI: define conventions for embeddings operations
(#1603)
Co-authored-by: Alexander Wert
---
.chloggen/1603.yaml | 22 ++++++++++++++++++++++
CONTRIBUTING.md | 2 +-
docs/attributes-registry/gen-ai.md | 10 +++++++---
docs/gen-ai/azure-ai-inference.md | 14 +++++++++-----
docs/gen-ai/gen-ai-metrics.md | 15 ++++++++++-----
docs/gen-ai/gen-ai-spans.md | 17 +++++++++++------
docs/gen-ai/openai.md | 14 +++++++++-----
model/gen-ai/registry.yaml | 14 ++++++++++++++
model/gen-ai/spans.yaml | 2 ++
9 files changed, 85 insertions(+), 25 deletions(-)
create mode 100644 .chloggen/1603.yaml
diff --git a/.chloggen/1603.yaml b/.chloggen/1603.yaml
new file mode 100644
index 0000000000..3917138a18
--- /dev/null
+++ b/.chloggen/1603.yaml
@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: gen-ai
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add conventions for GenAI Embeddings operations
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1174, 1603]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e91fa46805..e0a1c34a17 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -114,7 +114,7 @@ The YAML (model definition) and Markdown (documentation) files are organized in
```
All attributes must be defined in the folder matching their root namespace under
-`/{root-namespace}/*registry.yaml` file.
+`/model/{root-namespace}/registry.yaml` file.
Corresponding markdown files are auto-generated (see [Update the markdown files](#2-update-the-markdown-files))
in `/docs/attribute_registry` folder.
diff --git a/docs/attributes-registry/gen-ai.md b/docs/attributes-registry/gen-ai.md
index 105ab4761f..6606150d2e 100644
--- a/docs/attributes-registry/gen-ai.md
+++ b/docs/attributes-registry/gen-ai.md
@@ -16,7 +16,8 @@ This document defines the attributes used to describe telemetry in the context o
| Attribute | Type | Description | Examples | Stability |
|---|---|---|---|---|
-| `gen_ai.operation.name` | string | The name of the operation being performed. [1] | `chat`; `text_completion` |  |
+| `gen_ai.operation.name` | string | The name of the operation being performed. [1] | `chat`; `text_completion`; `embeddings` |  |
+| `gen_ai.request.encoding_formats` | string[] | The encoding formats requested in an embeddings operation, if specified. [2] | `["base64"]`; `["float", "binary"]` |  |
| `gen_ai.request.frequency_penalty` | double | The frequency penalty setting for the GenAI request. | `0.1` |  |
| `gen_ai.request.max_tokens` | int | The maximum number of tokens the model generates for a request. | `100` |  |
| `gen_ai.request.model` | string | The name of the GenAI model a request is being made to. | `gpt-4` |  |
@@ -28,14 +29,16 @@ This document defines the attributes used to describe telemetry in the context o
| `gen_ai.response.finish_reasons` | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]`; `["stop", "length"]` |  |
| `gen_ai.response.id` | string | The unique identifier for the completion. | `chatcmpl-123` |  |
| `gen_ai.response.model` | string | The name of the model that generated the response. | `gpt-4-0613` |  |
-| `gen_ai.system` | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` |  |
+| `gen_ai.system` | string | The Generative AI product as identified by the client or server instrumentation. [3] | `openai` |  |
| `gen_ai.token.type` | string | The type of token being counted. | `input`; `output` |  |
| `gen_ai.usage.input_tokens` | int | The number of tokens used in the GenAI input (prompt). | `100` |  |
| `gen_ai.usage.output_tokens` | int | The number of tokens used in the GenAI response (completion). | `180` |  |
**[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
-**[2] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified
+**[2] `gen_ai.request.encoding_formats`:** In some GenAI systems the encoding formats are called embedding types. Also, some GenAI systems only accept a single format per request.
+
+**[3] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified
by `gen_ai.request.model` and `gen_ai.response.model` attributes.
The actual GenAI product may differ from the one identified by the client.
@@ -52,6 +55,7 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
| Value | Description | Stability |
|---|---|---|
| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
+| `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
---
diff --git a/docs/gen-ai/azure-ai-inference.md b/docs/gen-ai/azure-ai-inference.md
index 1efd3ed907..ad9be5fb7a 100644
--- a/docs/gen-ai/azure-ai-inference.md
+++ b/docs/gen-ai/azure-ai-inference.md
@@ -23,11 +23,12 @@ The Semantic Conventions for [Azure AI Inference](https://learn.microsoft.com/az
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` |  |
+| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion`; `embeddings` | `Required` |  |
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error |  |
| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [3] | `gpt-4` | `Conditionally Required` If available. |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [4] | `80`; `8080`; `443` | `Conditionally Required` If not default (443). |  |
| [`az.namespace`](/docs/attributes-registry/azure.md) | string | [Azure Resource Provider Namespace](https://learn.microsoft.com/azure/azure-resource-manager/management/azure-services-resource-providers) as recognized by the client. [5] | `Microsoft.CognitiveServices` | `Recommended` |  |
+| [`gen_ai.request.encoding_formats`](/docs/attributes-registry/gen-ai.md) | string[] | The encoding formats requested in an embeddings operation, if specified. [6] | `["base64"]`; `["float", "binary"]` | `Recommended` |  |
| [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` |  |
| [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` |  |
| [`gen_ai.request.presence_penalty`](/docs/attributes-registry/gen-ai.md) | double | The presence penalty setting for the GenAI request. | `0.1` | `Recommended` |  |
@@ -36,10 +37,10 @@ The Semantic Conventions for [Azure AI Inference](https://learn.microsoft.com/az
| [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the GenAI request. | `1.0` | `Recommended` |  |
| [`gen_ai.response.finish_reasons`](/docs/attributes-registry/gen-ai.md) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]`; `["stop", "length"]` | `Recommended` |  |
| [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` |  |
-| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [6] | `gpt-4-0613` | `Recommended` |  |
+| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [7] | `gpt-4-0613` | `Recommended` |  |
| [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of prompt tokens as reported in the usage prompt_tokens property of the response. | `100` | `Recommended` |  |
| [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of completion tokens as reported in the usage completion_tokens property of the response. | `180` | `Recommended` |  |
-| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
+| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
**[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
@@ -53,9 +54,11 @@ Instrumentations SHOULD document the list of errors they report.
**[5] `az.namespace`:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.CognitiveServices` for all operations performed by Azure AI Inference clients.
-**[6] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
+**[6] `gen_ai.request.encoding_formats`:** In some GenAI systems the encoding formats are called embedding types. Also, some GenAI systems only accept a single format per request.
-**[7] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[7] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
+
+**[8] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
---
@@ -72,6 +75,7 @@ Instrumentations SHOULD document the list of errors they report.
| Value | Description | Stability |
|---|---|---|
| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
+| `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
diff --git a/docs/gen-ai/gen-ai-metrics.md b/docs/gen-ai/gen-ai-metrics.md
index 126e1f75d9..6e0904d7fd 100644
--- a/docs/gen-ai/gen-ai-metrics.md
+++ b/docs/gen-ai/gen-ai-metrics.md
@@ -61,7 +61,7 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of [1, 4, 16, 64
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` |  |
+| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion`; `embeddings` | `Required` |  |
| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` |  |
| [`gen_ai.token.type`](/docs/attributes-registry/gen-ai.md) | string | The type of token being counted. | `input`; `output` | `Required` |  |
| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Conditionally Required` If available. |  |
@@ -92,6 +92,7 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
| Value | Description | Stability |
|---|---|---|
| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
+| `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
---
@@ -141,7 +142,7 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of [0.01, 0.02,
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` |  |
+| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion`; `embeddings` | `Required` |  |
| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` |  |
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error |  |
| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Conditionally Required` If available. |  |
@@ -184,6 +185,7 @@ Instrumentations SHOULD document the list of errors they report.
| Value | Description | Stability |
|---|---|---|
| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
+| `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
---
@@ -231,7 +233,7 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` |  |
+| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion`; `embeddings` | `Required` |  |
| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` |  |
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error |  |
| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Conditionally Required` If available. |  |
@@ -274,6 +276,7 @@ Instrumentations SHOULD document the list of errors they report.
| Value | Description | Stability |
|---|---|---|
| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
+| `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
---
@@ -321,7 +324,7 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` |  |
+| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion`; `embeddings` | `Required` |  |
| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` |  |
| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Conditionally Required` If available. |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [3] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. |  |
@@ -351,6 +354,7 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
| Value | Description | Stability |
|---|---|---|
| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
+| `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
---
@@ -397,7 +401,7 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` |  |
+| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion`; `embeddings` | `Required` |  |
| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` |  |
| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Conditionally Required` If available. |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [3] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. |  |
@@ -427,6 +431,7 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
| Value | Description | Stability |
|---|---|---|
| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
+| `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
---
diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md
index dee6688b6a..0129e2adb8 100644
--- a/docs/gen-ai/gen-ai-spans.md
+++ b/docs/gen-ai/gen-ai-spans.md
@@ -32,7 +32,8 @@ Semantic conventions for individual GenAI systems and frameworks MAY specify dif
## GenAI attributes
-These attributes track input data and metadata for a request to an GenAI model. Each attribute represents a concept that is common to most Generative AI clients.
+These attributes track input data and metadata for a request to a GenAI model. Each attribute represents a concept that is common to most Generative AI clients.
+Many of these attributes only apply to specific GenAI operations. For example, GenAI embeddings requests don't use output tokens, so `gen_ai.usage.output_tokens` does not apply to embeddings operations.
@@ -43,11 +44,12 @@ These attributes track input data and metadata for a request to an GenAI model.
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` |  |
+| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion`; `embeddings` | `Required` |  |
| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` |  |
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error |  |
| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [4] | `gpt-4` | `Conditionally Required` If available. |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [5] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. |  |
+| [`gen_ai.request.encoding_formats`](/docs/attributes-registry/gen-ai.md) | string[] | The encoding formats requested in an embeddings operation, if specified. [6] | `["base64"]`; `["float", "binary"]` | `Recommended` |  |
| [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` |  |
| [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` |  |
| [`gen_ai.request.presence_penalty`](/docs/attributes-registry/gen-ai.md) | double | The presence penalty setting for the GenAI request. | `0.1` | `Recommended` |  |
@@ -57,10 +59,10 @@ These attributes track input data and metadata for a request to an GenAI model.
| [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the GenAI request. | `1.0` | `Recommended` |  |
| [`gen_ai.response.finish_reasons`](/docs/attributes-registry/gen-ai.md) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]`; `["stop", "length"]` | `Recommended` |  |
| [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` |  |
-| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [6] | `gpt-4-0613` | `Recommended` |  |
+| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [7] | `gpt-4-0613` | `Recommended` |  |
| [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI input (prompt). | `100` | `Recommended` |  |
| [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI response (completion). | `180` | `Recommended` |  |
-| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
+| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
**[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
@@ -82,9 +84,11 @@ Instrumentations SHOULD document the list of errors they report.
**[5] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[6] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
+**[6] `gen_ai.request.encoding_formats`:** In some GenAI systems the encoding formats are called embedding types. Also, some GenAI systems only accept a single format per request.
-**[7] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[7] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
+
+**[8] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
---
@@ -101,6 +105,7 @@ Instrumentations SHOULD document the list of errors they report.
| Value | Description | Stability |
|---|---|---|
| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
+| `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
---
diff --git a/docs/gen-ai/openai.md b/docs/gen-ai/openai.md
index 1842f68e7f..0584c16344 100644
--- a/docs/gen-ai/openai.md
+++ b/docs/gen-ai/openai.md
@@ -36,7 +36,7 @@ attributes and ones specific the OpenAI.
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` |  |
+| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion`; `embeddings` | `Required` |  |
| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [2] | `gpt-4` | `Required` |  |
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error |  |
| [`gen_ai.openai.request.response_format`](/docs/attributes-registry/gen-ai.md) | string | The response format that is requested. | `json` | `Conditionally Required` if the request includes a response_format |  |
@@ -45,6 +45,7 @@ attributes and ones specific the OpenAI.
| [`gen_ai.openai.response.service_tier`](/docs/attributes-registry/gen-ai.md) | string | The service tier used for the response. | `scale`; `default` | `Conditionally Required` [5] |  |
| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [6] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. |  |
| [`gen_ai.openai.response.system_fingerprint`](/docs/attributes-registry/gen-ai.md) | string | A fingerprint to track any eventual change in the Generative AI environment. | `fp_44709d6fcb` | `Recommended` |  |
+| [`gen_ai.request.encoding_formats`](/docs/attributes-registry/gen-ai.md) | string[] | The encoding formats requested in an embeddings operation, if specified. [7] | `["base64"]`; `["float", "binary"]` | `Recommended` |  |
| [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` |  |
| [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` |  |
| [`gen_ai.request.presence_penalty`](/docs/attributes-registry/gen-ai.md) | double | The presence penalty setting for the GenAI request. | `0.1` | `Recommended` |  |
@@ -53,10 +54,10 @@ attributes and ones specific the OpenAI.
| [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the GenAI request. | `1.0` | `Recommended` |  |
| [`gen_ai.response.finish_reasons`](/docs/attributes-registry/gen-ai.md) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]`; `["stop", "length"]` | `Recommended` |  |
| [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` |  |
-| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [7] | `gpt-4-0613` | `Recommended` |  |
+| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [8] | `gpt-4-0613` | `Recommended` |  |
| [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the prompt sent to OpenAI. | `100` | `Recommended` |  |
| [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the completions from OpenAI. | `180` | `Recommended` |  |
-| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
+| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
**[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
@@ -72,9 +73,11 @@ Instrumentations SHOULD document the list of errors they report.
**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
-**[7] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
+**[7] `gen_ai.request.encoding_formats`:** In some GenAI systems the encoding formats are called embedding types. Also, some GenAI systems only accept a single format per request.
-**[8] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
+**[8] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
+
+**[9] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
---
@@ -110,6 +113,7 @@ Instrumentations SHOULD document the list of errors they report.
| Value | Description | Stability |
|---|---|---|
| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
+| `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
diff --git a/model/gen-ai/registry.yaml b/model/gen-ai/registry.yaml
index ecf76ca612..918b0a2f21 100644
--- a/model/gen-ai/registry.yaml
+++ b/model/gen-ai/registry.yaml
@@ -90,6 +90,16 @@ groups:
type: double
brief: The presence penalty setting for the GenAI request.
examples: [0.1]
+ - id: gen_ai.request.encoding_formats
+ stability: experimental
+ type: string[]
+ brief: The encoding formats requested in an embeddings operation, if specified.
+ examples:
+ - ['base64']
+ - ['float', 'binary']
+ note: >
+ In some GenAI systems the encoding formats are called embedding types.
+ Also, some GenAI systems only accept a single format per request.
- id: gen_ai.response.id
stability: experimental
type: string
@@ -143,6 +153,10 @@ groups:
value: "text_completion"
brief: 'Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions)'
stability: experimental
+ - id: embeddings
+ value: "embeddings"
+ brief: 'Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create)'
+ stability: experimental
brief: The name of the operation being performed.
note: >
If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic
diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml
index 69252f6673..e6a3c743be 100644
--- a/model/gen-ai/spans.yaml
+++ b/model/gen-ai/spans.yaml
@@ -26,6 +26,8 @@ groups:
requirement_level: recommended
- ref: gen_ai.request.presence_penalty
requirement_level: recommended
+ - ref: gen_ai.request.encoding_formats
+ requirement_level: recommended
- ref: gen_ai.response.id
requirement_level: recommended
- ref: gen_ai.response.model
From 07293edd52e2182f9c18e871bbff44958cf77271 Mon Sep 17 00:00:00 2001
From: Liudmila Molkova
Date: Wed, 27 Nov 2024 11:04:49 -0800
Subject: [PATCH 24/32] Rename `f eature_flag.system` back to
`feature_flag.provider_name` (#1614)
Co-authored-by: Daniel Dyla
Co-authored-by: Alexander Wert
---
.chloggen/1614.yaml | 4 ++++
docs/attributes-registry/feature-flag.md | 13 +------------
docs/feature-flags/feature-flags-logs.md | 2 +-
.../deprecated/registry-deprecated.yaml | 12 ------------
model/feature-flags/logs.yaml | 2 +-
model/feature-flags/registry.yaml | 2 +-
schema-next.yaml | 4 ----
7 files changed, 8 insertions(+), 31 deletions(-)
create mode 100644 .chloggen/1614.yaml
delete mode 100644 model/feature-flags/deprecated/registry-deprecated.yaml
diff --git a/.chloggen/1614.yaml b/.chloggen/1614.yaml
new file mode 100644
index 0000000000..a02203c0c2
--- /dev/null
+++ b/.chloggen/1614.yaml
@@ -0,0 +1,4 @@
+change_type: enhancement
+component: feature_flag
+note: Rename `feature_flag.system` back to `feature_flag.provider_name`
+issues: [1614]
diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md
index 19cc5666fb..974d365e37 100644
--- a/docs/attributes-registry/feature-flag.md
+++ b/docs/attributes-registry/feature-flag.md
@@ -6,9 +6,6 @@
# Feature Flag
-- [Feature Flag Attributes](#feature-flag-attributes)
-- [Deprecated Feature Flag Attributes](#deprecated-feature-flag-attributes)
-
## Feature Flag Attributes
This document defines attributes for Feature Flags.
@@ -19,8 +16,8 @@ This document defines attributes for Feature Flags.
| `feature_flag.evaluation.error.message` | string | A message explaining the nature of an error occurring during flag evaluation. | `Flag `header-color` expected type `string` but found type `number`` |  |
| `feature_flag.evaluation.reason` | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` |  |
| `feature_flag.key` | string | The lookup key of the feature flag. | `logo-color` |  |
+| `feature_flag.provider_name` | string | Identifies the feature flag provider. | `Flag Manager` |  |
| `feature_flag.set.id` | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) to which the feature flag belongs. | `proj-1`; `ab98sgs`; `service1/dev` |  |
-| `feature_flag.system` | string | Identifies the feature flag provider. | `Flag Manager` |  |
| `feature_flag.variant` | string | A semantic identifier for an evaluated flag value. [1] | `red`; `true`; `on` |  |
| `feature_flag.version` | string | The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. | `1`; `01ABCDEF` |  |
@@ -44,11 +41,3 @@ For example, the variant `red` maybe be used for the value `#c05543`.
| `static` | The resolved value is static (no dynamic evaluation). |  |
| `targeting_match` | The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting. |  |
| `unknown` | The reason for the resolved value could not be determined. |  |
-
-## Deprecated Feature Flag Attributes
-
-Describes deprecated Feature Flag attributes.
-
-| Attribute | Type | Description | Examples | Stability |
-|---|---|---|---|---|
-| `feature_flag.provider_name` | string | Deprecated, use `feature_flag.system` instead. | `Flag Manager` | 
Replaced by `feature_flag.system`. |
diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md
index b893a3f1a3..573e633788 100644
--- a/docs/feature-flags/feature-flags-logs.md
+++ b/docs/feature-flags/feature-flags-logs.md
@@ -64,8 +64,8 @@ A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag valu
| [`feature_flag.context.id`](/docs/attributes-registry/feature-flag.md) | string | The unique identifier for the flag evaluation context. For example, the targeting key. | `5157782b-2203-4c80-a857-dbbd5e7761db` | `Recommended` |  |
| [`feature_flag.evaluation.error.message`](/docs/attributes-registry/feature-flag.md) | string | A message explaining the nature of an error occurring during flag evaluation. | `Flag `header-color` expected type `string` but found type `number`` | `Recommended` [5] |  |
| [`feature_flag.evaluation.reason`](/docs/attributes-registry/feature-flag.md) | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | `Recommended` |  |
+| [`feature_flag.provider_name`](/docs/attributes-registry/feature-flag.md) | string | Identifies the feature flag provider. | `Flag Manager` | `Recommended` |  |
| [`feature_flag.set.id`](/docs/attributes-registry/feature-flag.md) | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) to which the feature flag belongs. | `proj-1`; `ab98sgs`; `service1/dev` | `Recommended` |  |
-| [`feature_flag.system`](/docs/attributes-registry/feature-flag.md) | string | Identifies the feature flag provider. | `Flag Manager` | `Recommended` |  |
| [`feature_flag.version`](/docs/attributes-registry/feature-flag.md) | string | The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. | `1`; `01ABCDEF` | `Recommended` |  |
**[1] `error.type`:** If one of these values applies, then it MUST be used; otherwise, a custom value MAY be used.
diff --git a/model/feature-flags/deprecated/registry-deprecated.yaml b/model/feature-flags/deprecated/registry-deprecated.yaml
deleted file mode 100644
index 2f3a681454..0000000000
--- a/model/feature-flags/deprecated/registry-deprecated.yaml
+++ /dev/null
@@ -1,12 +0,0 @@
-groups:
- - id: registry.feature_flag.deprecated
- type: attribute_group
- display_name: Deprecated Feature Flag Attributes
- brief: "Describes deprecated Feature Flag attributes."
- attributes:
- - id: feature_flag.provider_name
- type: string
- brief: 'Deprecated, use `feature_flag.system` instead.'
- stability: experimental
- deprecated: "Replaced by `feature_flag.system`."
- examples: ["Flag Manager"]
diff --git a/model/feature-flags/logs.yaml b/model/feature-flags/logs.yaml
index 0de7c95577..edcd75250c 100644
--- a/model/feature-flags/logs.yaml
+++ b/model/feature-flags/logs.yaml
@@ -17,7 +17,7 @@ groups:
- ref: feature_flag.variant
requirement_level:
conditionally_required: If feature flag provider supplies a variant or equivalent concept.
- - ref: feature_flag.system
+ - ref: feature_flag.provider_name
requirement_level: recommended
- ref: feature_flag.context.id
requirement_level: recommended
diff --git a/model/feature-flags/registry.yaml b/model/feature-flags/registry.yaml
index 76b1d5fe3c..4b2c70cfe3 100644
--- a/model/feature-flags/registry.yaml
+++ b/model/feature-flags/registry.yaml
@@ -11,7 +11,7 @@ groups:
stability: experimental
brief: The lookup key of the feature flag.
examples: ["logo-color"]
- - id: feature_flag.system
+ - id: feature_flag.provider_name
type: string
stability: experimental
brief: Identifies the feature flag provider.
diff --git a/schema-next.yaml b/schema-next.yaml
index de73f27640..9f8ae4c451 100644
--- a/schema-next.yaml
+++ b/schema-next.yaml
@@ -16,10 +16,6 @@ versions:
vcs.repository.ref.name: vcs.ref.head.name
vcs.repository.ref.revision: vcs.ref.head.revision
vcs.repository.ref.type: vcs.ref.head.type
- # https://github.com/open-telemetry/semantic-conventions/pull/1440
- - rename_attributes:
- attribute_map:
- feature_flag.provider_name: feature_flag.system
metrics:
changes:
From 7e1954b9c845f89c343663c512b45b98796a3f0b Mon Sep 17 00:00:00 2001
From: Liudmila Molkova
Date: Thu, 28 Nov 2024 02:26:33 -0800
Subject: [PATCH 25/32] Add Trask to SemConv maintainers (#1619)
Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
---
README.md | 1 +
1 file changed, 1 insertion(+)
diff --git a/README.md b/README.md
index e81f0e5698..df59f4526e 100644
--- a/README.md
+++ b/README.md
@@ -35,6 +35,7 @@ Maintainers ([@open-telemetry/specs-semconv-maintainers](https://github.com/orgs
- [Johannes Tax](https://github.com/pyohannes), Grafana Labs
- [Josh Suereth](https://github.com/jsuereth), Google
- [Liudmila Molkova](https://github.com/lmolkova), Microsoft
+- [Trask Stalnaker](https://github.com/trask), Microsoft
Emeritus Maintainers:
From 0edb9e2b42e37739fe53e10623d93809269dd300 Mon Sep 17 00:00:00 2001
From: Liudmila Molkova
Date: Thu, 28 Nov 2024 10:23:37 -0800
Subject: [PATCH 26/32] Prepare release 1.29.0 (#1626)
---
.chloggen/1372-vcs-metrics.yaml | 31 -
.chloggen/1393.yaml | 4 -
.chloggen/1423.yaml | 23 -
.chloggen/1440.yaml | 6 -
.chloggen/1472.yaml | 4 -
.chloggen/1482.yaml | 18 -
.chloggen/1506.yaml | 4 -
.chloggen/1548.yaml | 4 -
.chloggen/1559.yaml | 22 -
.chloggen/1560.yaml | 4 -
.chloggen/1565.yaml | 22 -
.chloggen/1566.yaml | 22 -
.chloggen/1574.yaml | 22 -
.chloggen/1591.yaml | 22 -
.chloggen/1603.yaml | 22 -
.chloggen/1614.yaml | 4 -
.chloggen/971.yaml | 22 -
.chloggen/add-cli-spans.yaml | 22 -
.chloggen/add-synthetic-source.yaml | 22 -
.chloggen/add-system-uptime.yaml | 17 -
.chloggen/add_genai_system_fingerprint.yaml | 22 -
.chloggen/add_k8s_network_metrics.yaml | 22 -
.chloggen/add_k8s_uptime_metrics.yaml | 22 -
.chloggen/add_network_interface.yaml | 22 -
.chloggen/add_paging_device_attr.yaml | 22 -
.chloggen/add_process_cgroup.yaml | 22 -
.chloggen/enum-values-separators.yaml | 22 -
.chloggen/fix-typo-messaging-schema.yaml | 4 -
.chloggen/geo_fields.yaml | 17 -
.chloggen/map-settle-span-kind.yaml | 5 -
.chloggen/process_uptime.yaml | 22 -
.chloggen/profiling-htlhash.yaml | 22 -
.chloggen/update-graphql-span-name.yaml | 4 -
...sers_sourabhjain_moreoperationmetrics.yaml | 22 -
.../users_sourabhjain_otelcosmosmetrics.yaml | 22 -
CHANGELOG.md | 70 +++
CONTRIBUTING.md | 2 +
README.md | 2 +-
docs/database/cosmosdb.md | 2 +-
docs/database/database-metrics.md | 4 +-
docs/database/database-spans.md | 4 +-
docs/dns/dns-metrics.md | 2 +-
docs/dotnet/dotnet-aspnetcore-metrics.md | 4 +-
docs/dotnet/dotnet-dns-metrics.md | 2 +-
docs/dotnet/dotnet-http-metrics.md | 4 +-
docs/dotnet/dotnet-kestrel-metrics.md | 4 +-
docs/dotnet/dotnet-signalr-metrics.md | 2 +-
docs/exceptions/exceptions-logs.md | 8 +-
docs/exceptions/exceptions-spans.md | 2 +-
docs/faas/aws-lambda.md | 4 +-
docs/faas/faas-metrics.md | 6 +-
docs/feature-flags/feature-flags-logs.md | 8 +-
docs/gen-ai/gen-ai-events.md | 2 +-
docs/gen-ai/gen-ai-metrics.md | 2 +-
docs/gen-ai/gen-ai-spans.md | 2 +-
docs/general/events.md | 4 +-
docs/general/logs.md | 4 +-
docs/general/metrics.md | 4 +-
docs/general/trace.md | 2 +-
docs/http/http-metrics.md | 6 +-
docs/http/http-spans.md | 6 +-
docs/messaging/messaging-metrics.md | 4 +-
docs/messaging/messaging-spans.md | 2 +-
docs/resource/README.md | 6 +-
docs/resource/cloudfoundry.md | 2 +-
docs/rpc/connect-rpc.md | 2 +-
docs/rpc/grpc.md | 4 +-
docs/runtime/jvm-metrics.md | 2 +-
docs/runtime/nodejs-metrics.md | 2 +-
docs/runtime/v8js-metrics.md | 4 +-
.../tools/update_specification_version.sh | 4 +-
model/database/common.yaml | 2 +-
model/database/spans.yaml | 2 +-
schema-next.yaml | 2 +-
schemas/1.29.0 | 539 ++++++++++++++++++
75 files changed, 675 insertions(+), 653 deletions(-)
delete mode 100644 .chloggen/1372-vcs-metrics.yaml
delete mode 100644 .chloggen/1393.yaml
delete mode 100644 .chloggen/1423.yaml
delete mode 100644 .chloggen/1440.yaml
delete mode 100644 .chloggen/1472.yaml
delete mode 100644 .chloggen/1482.yaml
delete mode 100644 .chloggen/1506.yaml
delete mode 100644 .chloggen/1548.yaml
delete mode 100644 .chloggen/1559.yaml
delete mode 100644 .chloggen/1560.yaml
delete mode 100644 .chloggen/1565.yaml
delete mode 100644 .chloggen/1566.yaml
delete mode 100644 .chloggen/1574.yaml
delete mode 100644 .chloggen/1591.yaml
delete mode 100644 .chloggen/1603.yaml
delete mode 100644 .chloggen/1614.yaml
delete mode 100644 .chloggen/971.yaml
delete mode 100644 .chloggen/add-cli-spans.yaml
delete mode 100644 .chloggen/add-synthetic-source.yaml
delete mode 100644 .chloggen/add-system-uptime.yaml
delete mode 100755 .chloggen/add_genai_system_fingerprint.yaml
delete mode 100755 .chloggen/add_k8s_network_metrics.yaml
delete mode 100755 .chloggen/add_k8s_uptime_metrics.yaml
delete mode 100755 .chloggen/add_network_interface.yaml
delete mode 100755 .chloggen/add_paging_device_attr.yaml
delete mode 100755 .chloggen/add_process_cgroup.yaml
delete mode 100755 .chloggen/enum-values-separators.yaml
delete mode 100644 .chloggen/fix-typo-messaging-schema.yaml
delete mode 100755 .chloggen/geo_fields.yaml
delete mode 100755 .chloggen/map-settle-span-kind.yaml
delete mode 100644 .chloggen/process_uptime.yaml
delete mode 100755 .chloggen/profiling-htlhash.yaml
delete mode 100644 .chloggen/update-graphql-span-name.yaml
delete mode 100644 .chloggen/users_sourabhjain_moreoperationmetrics.yaml
delete mode 100644 .chloggen/users_sourabhjain_otelcosmosmetrics.yaml
create mode 100644 schemas/1.29.0
diff --git a/.chloggen/1372-vcs-metrics.yaml b/.chloggen/1372-vcs-metrics.yaml
deleted file mode 100644
index 5c9faded46..0000000000
--- a/.chloggen/1372-vcs-metrics.yaml
+++ /dev/null
@@ -1,31 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: breaking
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: vcs
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Add the VCS metrics inspired by the GitHub Receiver
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [1372]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext: |
- Makes the following changes:
-
- - Add metrics `vcs.change.count`, `vcs.change.duration`, `vcs.change.time_to_approval`, `vcs.repository.count`, `vcs.ref.count`,
- `vcs.ref.lines_delta`, `vcs.ref.revisions_delta`, `vcs.ref.time`, `vcs.contributor.count`
- - The VCS attributes `vcs.change.state`, `vcs.revision_delta.direction` and `vcs.line_change.type` have been added to the registry.
- - The VCS ref attributes have been duplicated to `vcs.ref.base.*` to allow for ref comparisons.
- - The VCS attribute `vcs.ref.type` has been added for simplicity when neither a full head or base ref is necessary.
- - `vcs.repository.change.*` attributes have been deprecated and moved to `vcs.change.*`.
- - `vcs.repository.ref.*` attributes have been deprecated and moved to `vcs.ref.head.*`.
diff --git a/.chloggen/1393.yaml b/.chloggen/1393.yaml
deleted file mode 100644
index c62971bbc9..0000000000
--- a/.chloggen/1393.yaml
+++ /dev/null
@@ -1,4 +0,0 @@
-change_type: enhancement
-component: gen_ai
-note: Add system-specific conventions for Azure AI Inference.
-issues: [1393]
diff --git a/.chloggen/1423.yaml b/.chloggen/1423.yaml
deleted file mode 100644
index ec61d6449c..0000000000
--- a/.chloggen/1423.yaml
+++ /dev/null
@@ -1,23 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: bug_fix
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: service
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: "Merge `resource` experimental and stable groups for service and telemetry.sdk"
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [1423]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext: |
- Discovered when fixing [weaver#306](https://github.com/open-telemetry/weaver/issues/306#issue-2458430277)
diff --git a/.chloggen/1440.yaml b/.chloggen/1440.yaml
deleted file mode 100644
index f130197287..0000000000
--- a/.chloggen/1440.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-change_type: breaking
-component: feature_flag
-note: >
- Rename `feature_flag` event to `feature_flag.evaluation` event, define new feature flag attributes and provide body definition.
- Remove `feature_flag` span event definition in favor of log-based event.
-issues: [1440]
diff --git a/.chloggen/1472.yaml b/.chloggen/1472.yaml
deleted file mode 100644
index 1005b293fb..0000000000
--- a/.chloggen/1472.yaml
+++ /dev/null
@@ -1,4 +0,0 @@
-change_type: enhancement
-component: http
-note: Define how to handle experimental attributes in stable groups, add policies and move experimental HTTP attributes into stable HTTP groups (as opt_in).
-issues: [906, 1472]
diff --git a/.chloggen/1482.yaml b/.chloggen/1482.yaml
deleted file mode 100644
index 2f56c01780..0000000000
--- a/.chloggen/1482.yaml
+++ /dev/null
@@ -1,18 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: bug_fix
-component: db
-note: |
- Fix telemetry for complex queries:
-
- - introduce the `db.query.summary` attribute to provide a concise, low-cardinality
- representation of the query text.
- - use `db.query.summary` as the span name and as a recommended attribute on metrics.
- - avoid capturing `db.operation.name` and `db.collection.name` when the query
- involves multiple operations or collections, to prevent ambiguity.
-
-issues: [521, 805, 1159]
diff --git a/.chloggen/1506.yaml b/.chloggen/1506.yaml
deleted file mode 100644
index 3e5def4456..0000000000
--- a/.chloggen/1506.yaml
+++ /dev/null
@@ -1,4 +0,0 @@
-change_type: enhancement
-component: db, gen-ai, faas
-note: Relax wording for span kind - use SHOULD instead of MUST for logical operations.
-issues: [1315, 1506]
diff --git a/.chloggen/1548.yaml b/.chloggen/1548.yaml
deleted file mode 100644
index 9651a2a115..0000000000
--- a/.chloggen/1548.yaml
+++ /dev/null
@@ -1,4 +0,0 @@
-change_type: enhancement
-component: kestrel
-note: Add .NET 9 error reasons to Kestrel connection metric.
-issues: [1582]
diff --git a/.chloggen/1559.yaml b/.chloggen/1559.yaml
deleted file mode 100644
index 3c4b353889..0000000000
--- a/.chloggen/1559.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: breaking
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: db
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Generalize `db.query.parameter.` to `db.operation.parameter.`
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [ 1559 ]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/1560.yaml b/.chloggen/1560.yaml
deleted file mode 100644
index 35769898b7..0000000000
--- a/.chloggen/1560.yaml
+++ /dev/null
@@ -1,4 +0,0 @@
-change_type: enhancement
-component: db
-note: Specify how to set span status for database operations.
-issues: [1536, 1560]
diff --git a/.chloggen/1565.yaml b/.chloggen/1565.yaml
deleted file mode 100644
index f2de83d7f2..0000000000
--- a/.chloggen/1565.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: breaking
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: db
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Remove redis database index from the redis span name.
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [ 1449 ]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/1566.yaml b/.chloggen/1566.yaml
deleted file mode 100644
index 5b82a55e2a..0000000000
--- a/.chloggen/1566.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: breaking
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: db
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Don't capture `db.operation.name` and `db.collection.name` from query formats that support multiples.
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [ 1566 ]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/1574.yaml b/.chloggen/1574.yaml
deleted file mode 100644
index cc5fec2519..0000000000
--- a/.chloggen/1574.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: enhancement
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: gen-ai
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Add 2 well-known gen-ai systems as reference values of the gen-ai system attribute including AWS Bedrock and IBM Watsonx AI
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [ 1574 ]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/1591.yaml b/.chloggen/1591.yaml
deleted file mode 100644
index e035bbbb24..0000000000
--- a/.chloggen/1591.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: enhancement
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: http
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Relax `server.port` requirement level on HTTP server spans
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [ 1387 ]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/1603.yaml b/.chloggen/1603.yaml
deleted file mode 100644
index 3917138a18..0000000000
--- a/.chloggen/1603.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: enhancement
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: gen-ai
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Add conventions for GenAI Embeddings operations
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [1174, 1603]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/1614.yaml b/.chloggen/1614.yaml
deleted file mode 100644
index a02203c0c2..0000000000
--- a/.chloggen/1614.yaml
+++ /dev/null
@@ -1,4 +0,0 @@
-change_type: enhancement
-component: feature_flag
-note: Rename `feature_flag.system` back to `feature_flag.provider_name`
-issues: [1614]
diff --git a/.chloggen/971.yaml b/.chloggen/971.yaml
deleted file mode 100644
index 874082aab4..0000000000
--- a/.chloggen/971.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: bug_fix
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: url
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Specific URL query string values should now be redacted by default due to concerns around leaking credentials.
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [ 971 ]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/add-cli-spans.yaml b/.chloggen/add-cli-spans.yaml
deleted file mode 100644
index 428bb1d701..0000000000
--- a/.chloggen/add-cli-spans.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: 'new_component'
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: 'cli'
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Define span describing CLI application execution
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [1577]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/add-synthetic-source.yaml b/.chloggen/add-synthetic-source.yaml
deleted file mode 100644
index 935eb5529e..0000000000
--- a/.chloggen/add-synthetic-source.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: enhancement
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: user_agent
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Add the `user_agent.synthetic.type` attribute to specify the category of synthetic traffic, such as tests or bots.
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [1127]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/add-system-uptime.yaml b/.chloggen/add-system-uptime.yaml
deleted file mode 100644
index a9c3e49c0d..0000000000
--- a/.chloggen/add-system-uptime.yaml
+++ /dev/null
@@ -1,17 +0,0 @@
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: enhancement
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: system
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Add system uptime metric
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [648]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/add_genai_system_fingerprint.yaml b/.chloggen/add_genai_system_fingerprint.yaml
deleted file mode 100755
index 807a4ac8ec..0000000000
--- a/.chloggen/add_genai_system_fingerprint.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: enhancement
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: gen-ai
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Add `gen_ai.openai.response.system_fingerprint` attribute
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [1355]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/add_k8s_network_metrics.yaml b/.chloggen/add_k8s_network_metrics.yaml
deleted file mode 100755
index 979248f208..0000000000
--- a/.chloggen/add_k8s_network_metrics.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: enhancement
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: k8s
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Add k8s.{node,pod}.network.{io,errors} metrics
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [1427]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/add_k8s_uptime_metrics.yaml b/.chloggen/add_k8s_uptime_metrics.yaml
deleted file mode 100755
index b0507f1d2b..0000000000
--- a/.chloggen/add_k8s_uptime_metrics.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: enhancement
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: k8s
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Add uptime metrics for container, K8s Pod and K8s Node
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [1486]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/add_network_interface.yaml b/.chloggen/add_network_interface.yaml
deleted file mode 100755
index 0225bf1d6f..0000000000
--- a/.chloggen/add_network_interface.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: breaking
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: system
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Introduce `network.interface.name` and use that instead of `system.device` for system and container network metrics
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [1492]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/add_paging_device_attr.yaml b/.chloggen/add_paging_device_attr.yaml
deleted file mode 100755
index 7937ed28f6..0000000000
--- a/.chloggen/add_paging_device_attr.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: 'breaking'
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: system
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Add system.device attribute to system paging metrics
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [1408]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/add_process_cgroup.yaml b/.chloggen/add_process_cgroup.yaml
deleted file mode 100755
index 5f32a6ac9c..0000000000
--- a/.chloggen/add_process_cgroup.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: 'enhancement'
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: linux
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Add linux.process.cgroup attribute
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [1357]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/enum-values-separators.yaml b/.chloggen/enum-values-separators.yaml
deleted file mode 100755
index 9fa166d99b..0000000000
--- a/.chloggen/enum-values-separators.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: enhancement
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: docs
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Improve separation between attribute table footnotes and enum values
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [1569]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/fix-typo-messaging-schema.yaml b/.chloggen/fix-typo-messaging-schema.yaml
deleted file mode 100644
index c487a03f06..0000000000
--- a/.chloggen/fix-typo-messaging-schema.yaml
+++ /dev/null
@@ -1,4 +0,0 @@
-change_type: 'bug_fix'
-component: messaging
-note: Fix typo in schemas for messaging attribute changes
-issues: [1595]
diff --git a/.chloggen/geo_fields.yaml b/.chloggen/geo_fields.yaml
deleted file mode 100755
index 452a456333..0000000000
--- a/.chloggen/geo_fields.yaml
+++ /dev/null
@@ -1,17 +0,0 @@
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: new_component
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: geo
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Add geo fields to attribute registry.
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [1033]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/map-settle-span-kind.yaml b/.chloggen/map-settle-span-kind.yaml
deleted file mode 100755
index 4fe6035ebe..0000000000
--- a/.chloggen/map-settle-span-kind.yaml
+++ /dev/null
@@ -1,5 +0,0 @@
-change_type: enhancement
-component: messaging
-note: Specify which span kind to use for messaging settle operations
-issues: [1478]
-subtext:
diff --git a/.chloggen/process_uptime.yaml b/.chloggen/process_uptime.yaml
deleted file mode 100644
index 3cbb447101..0000000000
--- a/.chloggen/process_uptime.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: breaking
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: process
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Change process.uptime instrument to a gauge.
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [1518]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/profiling-htlhash.yaml b/.chloggen/profiling-htlhash.yaml
deleted file mode 100755
index 56655b6957..0000000000
--- a/.chloggen/profiling-htlhash.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: breaking
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: process.executable.build_id
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Rename process.executable.build_id.profiling to process.executable.build_id.htlhash.
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [1520]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext: With https://github.com/open-telemetry/opentelemetry-specification/pull/4197 it was decided to rename the attribute profiling in process.executable.build_id to htlhash.
diff --git a/.chloggen/update-graphql-span-name.yaml b/.chloggen/update-graphql-span-name.yaml
deleted file mode 100644
index 1f0cc3f50e..0000000000
--- a/.chloggen/update-graphql-span-name.yaml
+++ /dev/null
@@ -1,4 +0,0 @@
-change_type: breaking
-component: graphql
-note: Update the GraphQL Span name convention
-issues: [1361]
diff --git a/.chloggen/users_sourabhjain_moreoperationmetrics.yaml b/.chloggen/users_sourabhjain_moreoperationmetrics.yaml
deleted file mode 100644
index 8c2dad39df..0000000000
--- a/.chloggen/users_sourabhjain_moreoperationmetrics.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: enhancement
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: db
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Added `db.cosmosdb.regions_contacted` attribute to Cosmos DB metrics and traces.
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [1525]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml b/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml
deleted file mode 100644
index 34a4940925..0000000000
--- a/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Use this changelog template to create an entry for release notes.
-#
-# If your change doesn't affect end users you should instead start
-# your pull request title with [chore] or use the "Skip Changelog" label.
-
-# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
-change_type: enhancement
-
-# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
-component: db
-
-# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: "Added new common `db.client.response.returned_rows` database metric and several operation level metrics for Azure Cosmos DB."
-
-# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
-# The values here must be integers.
-issues: [1438]
-
-# (Optional) One or more lines of additional information to render under the primary note.
-# These lines will be padded with 2 spaces and then inserted directly into the document.
-# Use pipe (|) for multiline entries.
-subtext:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 844007861b..e245552a74 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,76 @@
+## v1.29.0
+
+### 🛑 Breaking changes 🛑
+
+- `vcs`: Add the VCS metrics inspired by the GitHub Receiver (#1372)
+ Makes the following changes:
+
+ - Add metrics `vcs.change.count`, `vcs.change.duration`, `vcs.change.time_to_approval`, `vcs.repository.count`, `vcs.ref.count`,
+ `vcs.ref.lines_delta`, `vcs.ref.revisions_delta`, `vcs.ref.time`, `vcs.contributor.count`
+ - The VCS attributes `vcs.change.state`, `vcs.revision_delta.direction` and `vcs.line_change.type` have been added to the registry.
+ - The VCS ref attributes have been duplicated to `vcs.ref.base.*` to allow for ref comparisons.
+ - The VCS attribute `vcs.ref.type` has been added for simplicity when neither a full head or base ref is necessary.
+ - `vcs.repository.change.*` attributes have been deprecated and moved to `vcs.change.*`.
+ - `vcs.repository.ref.*` attributes have been deprecated and moved to `vcs.ref.head.*`.
+
+- `feature_flag`: Rename `feature_flag` event to `feature_flag.evaluation` event, define new feature flag attributes and provide body definition. Remove `feature_flag` span event definition in favor of log-based event.
+ (#1440)
+- `db`: Generalize `db.query.parameter.` to `db.operation.parameter.` (#1559)
+- `db`: Remove redis database index from the redis span name. (#1449)
+- `db`: Don't capture `db.operation.name` and `db.collection.name` from query formats that support multiples. (#1566)
+- `system`: Introduce `network.interface.name` and use that instead of `system.device` for system and container network metrics (#1492)
+- `system`: Add system.device attribute to system paging metrics (#1408)
+- `process`: Change process.uptime instrument to a gauge. (#1518)
+- `process.executable.build_id`: Rename process.executable.build_id.profiling to process.executable.build_id.htlhash. (#1520)
+ With [#4197](https://github.com/open-telemetry/opentelemetry-specification/pull/4197) it was decided to rename the attribute profiling in process.executable.build_id to htlhash.
+- `graphql`: Update the GraphQL Span name convention (#1361)
+
+### 🚀 New components 🚀
+
+- `cli`: Define span describing CLI application execution (#1577)
+- `geo`: Add geo fields to attribute registry. (#1033)
+
+### 💡 Enhancements 💡
+
+- `gen_ai`: Add system-specific conventions for Azure AI Inference. (#1393)
+- `http`: Define how to handle experimental attributes in stable groups, add policies and move experimental HTTP attributes into stable HTTP groups (as opt_in). (#906, #1472)
+- `db, gen-ai, faas`: Relax wording for span kind - use SHOULD instead of MUST for logical operations. (#1315, #1506)
+- `kestrel`: Add .NET 9 error reasons to Kestrel connection metric. (#1582)
+- `db`: Specify how to set span status for database operations. (#1536, #1560)
+- `gen-ai`: Add 2 well-known gen-ai systems as reference values of the gen-ai system attribute including AWS Bedrock and IBM Watsonx AI (#1574)
+- `http`: Relax `server.port` requirement level on HTTP server spans (#1387)
+- `gen-ai`: Add conventions for GenAI Embeddings operations (#1174, #1603)
+- `feature_flag`: Rename `feature_flag.system` back to `feature_flag.provider_name` (#1614)
+- `user_agent`: Add the `user_agent.synthetic.type` attribute to specify the category of synthetic traffic, such as tests or bots. (#1127)
+- `system`: Add system uptime metric (#648)
+- `gen-ai`: Add `gen_ai.openai.response.system_fingerprint` attribute (#1355)
+- `k8s`: Add k8s.{node,pod}.network.{io,errors} metrics (#1427)
+- `k8s`: Add uptime metrics for container, K8s Pod and K8s Node (#1486)
+- `linux`: Add linux.process.cgroup attribute (#1357)
+- `docs`: Improve separation between attribute table footnotes and enum values (#1569)
+- `messaging`: Specify which span kind to use for messaging settle operations (#1478)
+- `db`: Added `db.cosmosdb.regions_contacted` attribute to Cosmos DB metrics and traces. (#1525)
+- `db`: Added new common `db.client.response.returned_rows` database metric and several operation level metrics for Azure Cosmos DB. (#1438)
+
+### 🧰 Bug fixes 🧰
+
+- `service`: Merge `resource` experimental and stable groups for service and telemetry.sdk (#1423)
+ Discovered when fixing [weaver#306](https://github.com/open-telemetry/weaver/issues/306#issue-2458430277)
+
+- `db`: Fix telemetry for complex queries:
+
+- introduce the `db.query.summary` attribute to provide a concise, low-cardinality
+ representation of the query text.
+- use `db.query.summary` as the span name and as a recommended attribute on metrics.
+- avoid capturing `db.operation.name` and `db.collection.name` when the query
+ involves multiple operations or collections, to prevent ambiguity.
+ (#521, #805, #1159)
+- `url`: Specific URL query string values should now be redacted by default due to concerns around leaking credentials. (#971)
+- `messaging`: Fix typo in schemas for messaging attribute changes (#1595)
+
## v1.28.0
### 🛑 Breaking changes 🛑
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e0a1c34a17..5f764273a9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -366,6 +366,8 @@ make check-policies
- Ensure the referenced specification version is up to date. Use
[tooling to update the spec](#updating-the-referenced-specification-version)
if needed.
+- Run [opentelemetry.io workflow](https://github.com/open-telemetry/opentelemetry.io/actions/workflows/build-dev.yml)
+ against `semantic-conventions` submodule as a smoke-test for docs. Fix broken links, if any.
- Create a staging branch for the release.
- Update `schema-next.yaml` file and move to `schemas/{version}`
- Ensure the `next` version is appropriately configured as the `{version}`.
diff --git a/README.md b/README.md
index df59f4526e..8fbcb03ac5 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
[](https://github.com/open-telemetry/semantic-conventions/actions?query=workflow%3A%22Checks%22+branch%3Amain)
[](https://github.com/open-telemetry/semantic-conventions/releases/latest)
-[](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.37.0)
+[](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.39.0)
Semantic Conventions define a common set of (semantic) attributes which
provide meaning to data when collecting, producing and consuming it.
diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md
index 941ffd5ad3..f32d64d57d 100644
--- a/docs/database/cosmosdb.md
+++ b/docs/database/cosmosdb.md
@@ -322,7 +322,7 @@ This metric is [required][MetricRequired].
It captures the Request Units consumed by each operation in Azure Cosmos DB. Since Request Units serve as a form of throughput control within the Azure Cosmos DB database, monitoring their usage is crucial to avoid throttling.
this metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 1, 5, 10, 25, 50, 100, 250, 500, 1000]`.
Explaining bucket configuration:
diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md
index e7d2597bef..30af7d9790 100644
--- a/docs/database/database-metrics.md
+++ b/docs/database/database-metrics.md
@@ -65,7 +65,7 @@ This metric is [required][MetricRequired].
When this metric is reported alongside a database operation span, the metric value SHOULD be the same as the database operation span duration.
This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`.
@@ -241,7 +241,7 @@ The following metric instruments describe database query response.
This metric is [recommended][MetricRecommended].
This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[1, 2, 5, 10, 20, 50, 100, 200, 500, 1000, 2000, 5000, 10000]`.
Explaining bucket configuration:
diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md
index bf5dc93347..aa354baa1b 100644
--- a/docs/database/database-spans.md
+++ b/docs/database/database-spans.md
@@ -59,7 +59,7 @@ with all retries.
## Name
-Database spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/trace/api.md#span).
+Database spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#span).
The **span name** SHOULD be `{db.query.summary}` if a summary is available.
@@ -477,4 +477,4 @@ More specific Semantic Conventions are defined for the following database techno
* [SQL](sql.md): Semantic Conventions for *SQL* databases.
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
-[SpanStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/trace/api.md#set-status
+[SpanStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status
diff --git a/docs/dns/dns-metrics.md b/docs/dns/dns-metrics.md
index 43c8e0401a..9cdec3122d 100644
--- a/docs/dns/dns-metrics.md
+++ b/docs/dns/dns-metrics.md
@@ -24,7 +24,7 @@ This document defines semantic conventions to apply when instrumenting DNS queri
This metric is optional.
This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md
index 7ea3650573..76f65aa849 100644
--- a/docs/dotnet/dotnet-aspnetcore-metrics.md
+++ b/docs/dotnet/dotnet-aspnetcore-metrics.md
@@ -172,7 +172,7 @@ All rate-limiting metrics are reported by the `Microsoft.AspNetCore.RateLimiting
### Metric: `aspnetcore.rate_limiting.request_lease.duration`
this metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
@@ -228,7 +228,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
### Metric: `aspnetcore.rate_limiting.request.time_in_queue`
this metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md
index 332a0aa02d..43137549c8 100644
--- a/docs/dotnet/dotnet-dns-metrics.md
+++ b/docs/dotnet/dotnet-dns-metrics.md
@@ -20,7 +20,7 @@ This article defines semantic conventions for DNS metrics emitted by .NET.
### Metric: `dns.lookup.duration`
This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md
index 15553651b1..fd1f9c99fa 100644
--- a/docs/dotnet/dotnet-http-metrics.md
+++ b/docs/dotnet/dotnet-http-metrics.md
@@ -77,7 +77,7 @@ Notes:
### Metric: `http.client.connection.duration`
this metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
@@ -106,7 +106,7 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
### Metric: `http.client.request.time_in_queue`
this metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md
index 4f61ba5e1c..5bbb8d5d34 100644
--- a/docs/dotnet/dotnet-kestrel-metrics.md
+++ b/docs/dotnet/dotnet-kestrel-metrics.md
@@ -93,7 +93,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
## Metric: `kestrel.connection.duration`
this metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
@@ -474,7 +474,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
## Metric: `kestrel.tls_handshake.duration`
this metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md
index 91697e65e5..e4b0d24cdd 100644
--- a/docs/dotnet/dotnet-signalr-metrics.md
+++ b/docs/dotnet/dotnet-signalr-metrics.md
@@ -18,7 +18,7 @@ This article defines semantic conventions for SignalR metrics emitted by .NET co
## Metric: `signalr.server.connection.duration`
this metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
diff --git a/docs/exceptions/exceptions-logs.md b/docs/exceptions/exceptions-logs.md
index c799931ae2..b709aaf9d0 100644
--- a/docs/exceptions/exceptions-logs.md
+++ b/docs/exceptions/exceptions-logs.md
@@ -7,8 +7,8 @@ linkTitle: Logs
**Status**: [Stable][DocumentStatus]
This document defines semantic conventions for recording exceptions on
-[logs](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/bridge-api.md#emit-a-logrecord) and [events](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/event-api.md#emit-event)
-emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/bridge-api.md#logger).
+[logs](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.39.0/specification/logs/api.md#emit-a-logrecord) and [events](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.39.0/specification/logs/api.md#emit-an-event)
+emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/api.md#logger).
@@ -21,7 +21,7 @@ emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry
## Recording an Exception
Exceptions SHOULD be recorded as attributes on the
-[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/bridge-api.md#logger) emit
+[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/api.md#logger) emit
operations. Exceptions MAY be recorded on "logs" or "events" depending on the
context.
@@ -33,7 +33,7 @@ the language runtime.
## Attributes
The table below indicates which attributes should be added to the
-[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/data-model.md#log-and-event-record-definition) and their types.
+[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/data-model.md#log-and-event-record-definition) and their types.
diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md
index ab2cef6f29..afcb5a50c3 100644
--- a/docs/exceptions/exceptions-spans.md
+++ b/docs/exceptions/exceptions-spans.md
@@ -23,7 +23,7 @@ An exception SHOULD be recorded as an `Event` on the span during which it occurr
The name of the event MUST be `"exception"`.
A typical template for an auto-instrumentation implementing this semantic convention
-using an [API-provided `recordException` method](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/trace/api.md#record-exception)
+using an [API-provided `recordException` method](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#record-exception)
could look like this (pseudo-Java):
```java
diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md
index d3200038e7..c61a9a7f2f 100644
--- a/docs/faas/aws-lambda.md
+++ b/docs/faas/aws-lambda.md
@@ -163,7 +163,7 @@ be ` process`. If there are multiple sources in the batch, the nam
For every message in the event, the [message system attributes][] (not message attributes, which are provided by
the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be
-parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/context/api-propagators.md) and
+parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/context/api-propagators.md) and
added as a link to the span. This means the span may have as many links as messages in the batch.
See [compatibility](../non-normative/compatibility/aws.md#context-propagation) for more info.
@@ -176,7 +176,7 @@ See [compatibility](../non-normative/compatibility/aws.md#context-propagation) f
For the SQS message span, the name MUST be ` process`. The parent MUST be the `CONSUMER` span
corresponding to the SQS event. The [message system attributes][] (not message attributes, which are provided by
the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be
-parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/context/api-propagators.md) and
+parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/context/api-propagators.md) and
added as a link to the span.
See [compatibility](../non-normative/compatibility/aws.md#context-propagation) for more info.
diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md
index b14871df76..32920096f0 100644
--- a/docs/faas/faas-metrics.md
+++ b/docs/faas/faas-metrics.md
@@ -46,7 +46,7 @@ The following metrics are recorded by the FaaS instance.
This metric is [recommended][MetricRecommended].
This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
@@ -86,7 +86,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
This metric is [recommended][MetricRecommended].
This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
@@ -306,7 +306,7 @@ This metric is [recommended][MetricRecommended].
This metric is [recommended][MetricRecommended].
This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md
index 573e633788..1f601e9e71 100644
--- a/docs/feature-flags/feature-flags-logs.md
+++ b/docs/feature-flags/feature-flags-logs.md
@@ -7,8 +7,8 @@ linkTitle: Logs
**Status**: [Experimental][DocumentStatus]
This document defines semantic conventions for recording feature flag evaluations as
-a [log record](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/data-model.md#log-and-event-record-definition) emitted through the
-[Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/bridge-api.md#emit-a-logrecord).
+a [log record](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/data-model.md#log-and-event-record-definition) emitted through the
+[Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/api.md#emit-a-logrecord).
This is useful when a flag is evaluated outside of a transaction context
such as when the application loads or on a timer.
@@ -32,14 +32,14 @@ This can be used to determine the impact a feature has on a request, enabling en
## Recording an Evaluation
Feature flag evaluations SHOULD be recorded as attributes on the
-[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/bridge-api.md#logger) emit
+[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/api.md#logger) emit
operations. Evaluations MAY be recorded on "logs" or "events" depending on the
context.
## Evaluation event
The table below indicates which attributes should be added to the
-[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/data-model.md#log-and-event-record-definition) and their types.
+[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/data-model.md#log-and-event-record-definition) and their types.
diff --git a/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md
index be2ded85e5..e786696f29 100644
--- a/docs/gen-ai/gen-ai-events.md
+++ b/docs/gen-ai/gen-ai-events.md
@@ -27,7 +27,7 @@ linkTitle: Generative AI events
-GenAI instrumentations MAY capture user inputs sent to the model and responses received from it as [events](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/event-api.md).
+GenAI instrumentations MAY capture user inputs sent to the model and responses received from it as [events](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/event-api.md).
> Note:
> Event API is experimental and not yet available in some languages. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md#events) to see the implementation status in corresponding language.
diff --git a/docs/gen-ai/gen-ai-metrics.md b/docs/gen-ai/gen-ai-metrics.md
index 6e0904d7fd..f47e0b2280 100644
--- a/docs/gen-ai/gen-ai-metrics.md
+++ b/docs/gen-ai/gen-ai-metrics.md
@@ -456,4 +456,4 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
[MetricRequired]: /docs/general/metric-requirement-level.md#required
[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
-[ExplicitBucketBoundaries]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters
+[ExplicitBucketBoundaries]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters
diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md
index 0129e2adb8..70c8d3d5bf 100644
--- a/docs/gen-ai/gen-ai-spans.md
+++ b/docs/gen-ai/gen-ai-spans.md
@@ -26,7 +26,7 @@ instrumented protocol such as HTTP.
## Name
-GenAI spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/trace/api.md#span).
+GenAI spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#span).
The **span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`.
Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format.
diff --git a/docs/general/events.md b/docs/general/events.md
index da314d9bf6..15ae55be53 100644
--- a/docs/general/events.md
+++ b/docs/general/events.md
@@ -55,7 +55,7 @@ structure and semantics will also be defined.
### General event semantics
* An event MUST have an `event.name` attribute that uniquely identifies the event.
-* It MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/common#attribute)
+* It MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute)
attributes that provide additional context about the event.
* It MAY contain a _payload_ (body) that describes the specific details of the
named event.
@@ -70,7 +70,7 @@ structure and semantics will also be defined.
Recommendations for defining events:
* Use the _payload_ (body) to represent the details of the event instead of a
- collection of [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/common#attribute)
+ collection of [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute)
attributes.
* Events SHOULD be generated / produced / recorded using the
[Event API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/event-api.md)
diff --git a/docs/general/logs.md b/docs/general/logs.md
index eeaa529605..030396b0d5 100644
--- a/docs/general/logs.md
+++ b/docs/general/logs.md
@@ -28,7 +28,7 @@ The following semantic conventions for logs are defined:
* [Feature Flags](/docs/feature-flags/feature-flags-logs.md): Semantic attributes that may be used in describing feature flag evaluations in logs.
Apart from semantic conventions for logs, [events](events.md), [traces](trace.md), and [metrics](metrics.md),
-OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/resource/sdk.md) with their own
+OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md) with their own
[Resource Semantic Conventions](/docs/resource/README.md).
## General log identification attributes
@@ -61,7 +61,7 @@ The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID
This section describes attributes for log media in OpenTelemetry. Log media are mechanisms by which logs are transmitted. Types of media include files, streams, network protocols, and os-specific logging services such as journald and Windows Event Log.
-**Note:** The OpenTelemetry specification defines a [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/resource/sdk.md) as `an immutable representation of the entity producing telemetry`.
+**Note:** The OpenTelemetry specification defines a [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md) as `an immutable representation of the entity producing telemetry`.
The following attributes do not describe entities that produce telemetry. Rather, they describe mechanisms of log transmission.
As such, these should be recorded as Log Record attributes when applicable. They should not be recorded as Resource attributes.
diff --git a/docs/general/metrics.md b/docs/general/metrics.md
index b69930e674..fbe38ea7c4 100644
--- a/docs/general/metrics.md
+++ b/docs/general/metrics.md
@@ -40,7 +40,7 @@ The following semantic conventions surrounding metrics are defined:
* [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics.
Apart from semantic conventions for metrics, [traces](trace.md), [logs](logs.md), and [events](events.md), OpenTelemetry also
-defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/resource/sdk.md) with
+defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md) with
their own [Resource Semantic Conventions](/docs/resource/README.md).
## General Guidelines
@@ -124,7 +124,7 @@ usable.
When building components that interoperate between OpenTelemetry and a system
using the OpenMetrics exposition format, use the
-[OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/compatibility/prometheus_and_openmetrics.md).
+[OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/compatibility/prometheus_and_openmetrics.md).
### Naming rules for Counters and UpDownCounters
diff --git a/docs/general/trace.md b/docs/general/trace.md
index 565913a31b..591e306ad1 100644
--- a/docs/general/trace.md
+++ b/docs/general/trace.md
@@ -33,7 +33,7 @@ The following semantic conventions for spans are defined:
* [RPC/RMI](/docs/rpc/rpc-spans.md): For remote procedure call (e.g., gRPC) spans.
Apart from semantic conventions for traces, [metrics](metrics.md), [logs](logs.md), and [events](events.md),
-OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/resource/sdk.md) with their own
+OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md) with their own
[Resource Semantic Conventions](/docs/resource/README.md).
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md
index a5136e6d5e..60c9b9f09e 100644
--- a/docs/http/http-metrics.md
+++ b/docs/http/http-metrics.md
@@ -64,7 +64,7 @@ This metric is required.
When this metric is reported alongside an HTTP server span, the metric value SHOULD be the same as the HTTP server span duration.
This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
@@ -511,7 +511,7 @@ This metric is required.
When this metric is reported alongside an HTTP client span, the metric value SHOULD be the same as the HTTP client span duration.
This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
@@ -864,7 +864,7 @@ This metric is optional.
### Metric: `http.client.connection.duration`
This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
This metric is optional.
diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md
index 967db6d643..0b382115cf 100644
--- a/docs/http/http-spans.md
+++ b/docs/http/http-spans.md
@@ -64,7 +64,7 @@ and various HTTP versions like 1.1, 2 and SPDY.
## Name
-HTTP spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/trace/api.md#span).
+HTTP spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#span).
HTTP span names SHOULD be `{method} {target}` if there is a (low-cardinality) `target` available. If there is no (low-cardinality) `{target}` available, HTTP span names SHOULD be `{method}`.
@@ -86,7 +86,7 @@ Instrumentation MUST NOT default to using URI path as a `{target}`.
## Status
-[Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/trace/api.md#set-status) MUST be left unset if HTTP status code was in the
+[Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status) MUST be left unset if HTTP status code was in the
1xx, 2xx or 3xx ranges, unless there was another error (e.g., network error receiving
the response body; or 3xx codes with max redirects exceeded), in which case status
MUST be set to `Error`.
@@ -743,4 +743,4 @@ Span name: `POST /uploads/:document_id`.
| `error.type` | `WebSocketDisconnect` |
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
-[SpanProcessor]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/trace/sdk.md#span-processor
+[SpanProcessor]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/sdk.md#span-processor
diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md
index 3e26dcf624..87e6ff8467 100644
--- a/docs/messaging/messaging-metrics.md
+++ b/docs/messaging/messaging-metrics.md
@@ -53,7 +53,7 @@ When this metric is reported alongside a messaging span, the metric value SHOULD
This metric is [required][MetricRequired].
This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
@@ -367,7 +367,7 @@ When this metric is reported alongside a messaging process span, the metric valu
This metric is [required][MetricRequired] for push-based message delivery and is [recommended][MetricRecommended] for processing operations instrumented for pull-based scenarios.
This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md
index 1b00dc2b3e..73a90bdd81 100644
--- a/docs/messaging/messaging-spans.md
+++ b/docs/messaging/messaging-spans.md
@@ -187,7 +187,7 @@ in such a way that it cannot be changed by intermediaries.
### Span name
-Messaging spans SHOULD follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/trace/api.md#span).
+Messaging spans SHOULD follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#span).
diff --git a/docs/resource/README.md b/docs/resource/README.md
index 9f2f92f533..b687ade923 100644
--- a/docs/resource/README.md
+++ b/docs/resource/README.md
@@ -9,7 +9,7 @@ path_base_for_github_subdir:
**Status**: [Mixed][DocumentStatus]
-This document defines standard attributes for resources. These attributes are typically used in the [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/resource/sdk.md) and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from
+This document defines standard attributes for resources. These attributes are typically used in the [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md) and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from
[OpenCensus Resource standard](https://github.com/census-instrumentation/opencensus-specs/blob/master/resource/StandardResources.md).
@@ -58,14 +58,14 @@ Given their significance some resource attributes are treated specifically as de
### Semantic Attributes with Dedicated Environment Variable
These are the attributes which MAY be configurable via a dedicated environment variable
-as specified in [OpenTelemetry Environment Variable Specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/configuration/sdk-environment-variables.md):
+as specified in [OpenTelemetry Environment Variable Specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/configuration/sdk-environment-variables.md):
- [`service.name`](#service)
### Semantic Attributes with SDK-provided Default Value
These are the attributes which MUST be provided by the SDK
-as specified in the [Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/resource/sdk.md#sdk-provided-resource-attributes):
+as specified in the [Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md#sdk-provided-resource-attributes):
- [`service.name`](#service)
- [`telemetry.sdk` group](#telemetry-sdk)
diff --git a/docs/resource/cloudfoundry.md b/docs/resource/cloudfoundry.md
index 71f363de8d..7149437f8f 100644
--- a/docs/resource/cloudfoundry.md
+++ b/docs/resource/cloudfoundry.md
@@ -201,4 +201,4 @@ should be used. The `system.instance.id` should be set to `spec.id`.
-[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/document-status.md
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/document-status.md
diff --git a/docs/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md
index 44ddac0d0c..57e1f3bd0c 100644
--- a/docs/rpc/connect-rpc.md
+++ b/docs/rpc/connect-rpc.md
@@ -65,6 +65,6 @@ Below is a table of attributes that SHOULD be included on client and server Conn
## Connect RPC Status
-If `rpc.connect_rpc.error_code` is set, [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/trace/api.md#set-status) MUST be set to `Error` and left unset in all other cases.
+If `rpc.connect_rpc.error_code` is set, [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status) MUST be set to `Error` and left unset in all other cases.
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md
index 67c3b1b7ca..11fbc5807f 100644
--- a/docs/rpc/grpc.md
+++ b/docs/rpc/grpc.md
@@ -65,10 +65,10 @@ Below is a table of attributes that SHOULD be included on client and server gRPC
## gRPC Status
The table below describes when
-the [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/trace/api.md#set-status) MUST be set
+the [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status) MUST be set
to `Error` or remain unset
depending on the [gRPC status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md)
-and [Span Kind](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/trace/api.md#spankind).
+and [Span Kind](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#spankind).
| gRPC Status Code | `SpanKind.SERVER` Span Status | `SpanKind.CLIENT` Span Status |
|---|---|---|
diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md
index 9ef4d1bade..2536649713 100644
--- a/docs/runtime/jvm-metrics.md
+++ b/docs/runtime/jvm-metrics.md
@@ -206,7 +206,7 @@ This metric is obtained by subscribing to
[`GarbageCollectionNotificationInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GarbageCollectionNotificationInfo.html) events provided by [`GarbageCollectorMXBean`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/GarbageCollectorMXBean.html). The duration value is obtained from [`GcInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GcInfo.html#getDuration--)
This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.01, 0.1, 1, 10 ]`.
diff --git a/docs/runtime/nodejs-metrics.md b/docs/runtime/nodejs-metrics.md
index 86754eb5db..ab4c498b63 100644
--- a/docs/runtime/nodejs-metrics.md
+++ b/docs/runtime/nodejs-metrics.md
@@ -246,6 +246,6 @@ This metric is [recommended][MetricRecommended].
-[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/document-status.md
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/document-status.md
[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
[Eventloop]: https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions
diff --git a/docs/runtime/v8js-metrics.md b/docs/runtime/v8js-metrics.md
index 83be405a9e..c26f429c16 100644
--- a/docs/runtime/v8js-metrics.md
+++ b/docs/runtime/v8js-metrics.md
@@ -32,7 +32,7 @@ This document describes semantic conventions for V8 JS Engine Runtime metrics in
This metric is [recommended][MetricRecommended].
This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters)
of `[ 0.01, 0.1, 1, 10 ]`.
@@ -228,5 +228,5 @@ This metric is [recommended][MetricRecommended].
-[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/document-status.md
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/document-status.md
[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
diff --git a/internal/tools/update_specification_version.sh b/internal/tools/update_specification_version.sh
index 490d64ba64..a57c766eb0 100755
--- a/internal/tools/update_specification_version.sh
+++ b/internal/tools/update_specification_version.sh
@@ -6,9 +6,9 @@
# Set this to the version number you want to CHANGE in URLs in the repository.
-PREVIOUS_SPECIFICATION_VERSION="v1.35.0"
+PREVIOUS_SPECIFICATION_VERSION="v1.37.0"
# Set this to the version number you want to KEEP in URLs in the repository.
-LATEST_SPECIFICATION_VERSION="v1.37.0"
+LATEST_SPECIFICATION_VERSION="v1.39.0"
# The specific pattern we look for when replacing URLs
SPECIFICATION_URL_PREFIX="https://github.com/open-telemetry/opentelemetry-specification/tree/"
SPECIFICATION_BLOB_URL_PREFIX="https://github.com/open-telemetry/opentelemetry-specification/blob/"
diff --git a/model/database/common.yaml b/model/database/common.yaml
index 7cb4429964..2e8fe7b188 100644
--- a/model/database/common.yaml
+++ b/model/database/common.yaml
@@ -37,7 +37,7 @@ groups:
# requirement_level:
# conditionally_required: if available
- ref: db.operation.name
- requirement_level: # TODO (trask) simplify
+ requirement_level: # TODO (trask) simplify
conditionally_required: >
If readily available and if there is a single operation name that describes the
database call. The operation name MAY be parsed from the query text,
diff --git a/model/database/spans.yaml b/model/database/spans.yaml
index 30ec2fe1e0..df0a993543 100644
--- a/model/database/spans.yaml
+++ b/model/database/spans.yaml
@@ -10,7 +10,7 @@ groups:
# sampling_relevant: true
- ref: db.operation.name
sampling_relevant: true
- requirement_level: # TODO (trask) simplify
+ requirement_level: # TODO (trask) simplify
conditionally_required: >
If readily available and if there is a single operation name that describes the
database call. The operation name MAY be parsed from the query text,
diff --git a/schema-next.yaml b/schema-next.yaml
index 9f8ae4c451..6fa7a3fb06 100644
--- a/schema-next.yaml
+++ b/schema-next.yaml
@@ -2,6 +2,7 @@ file_format: 1.1.0
schema_url: https://opentelemetry.io/schemas/next
versions:
next:
+ 1.29.0:
all:
changes:
# https://github.com/open-telemetry/semantic-conventions/pull/1520
@@ -16,7 +17,6 @@ versions:
vcs.repository.ref.name: vcs.ref.head.name
vcs.repository.ref.revision: vcs.ref.head.revision
vcs.repository.ref.type: vcs.ref.head.type
-
metrics:
changes:
# https://github.com/open-telemetry/semantic-conventions/pull/1492
diff --git a/schemas/1.29.0 b/schemas/1.29.0
new file mode 100644
index 0000000000..430cffe789
--- /dev/null
+++ b/schemas/1.29.0
@@ -0,0 +1,539 @@
+file_format: 1.1.0
+schema_url: https://opentelemetry.io/schemas/1.29.0
+versions:
+ 1.29.0:
+ all:
+ changes:
+ # https://github.com/open-telemetry/semantic-conventions/pull/1520
+ - rename_attributes:
+ attribute_map:
+ process.executable.build_id.profiling: process.executable.build_id.htlhash
+ # https://github.com/open-telemetry/semantic-conventions/pull/1383
+ - rename_attributes:
+ attribute_map:
+ vcs.repository.change.id: vcs.change.id
+ vcs.repository.change.title: vcs.change.title
+ vcs.repository.ref.name: vcs.ref.head.name
+ vcs.repository.ref.revision: vcs.ref.head.revision
+ vcs.repository.ref.type: vcs.ref.head.type
+
+ metrics:
+ changes:
+ # https://github.com/open-telemetry/semantic-conventions/pull/1492
+ - rename_attributes:
+ attribute_map:
+ system.device: network.interface.name
+ apply_to_metrics:
+ - container.network.io
+ - system.network.dropped
+ - system.network.errors
+ - system.network.io
+ - system.network.connections
+ 1.28.0:
+ metrics:
+ changes:
+ # https://github.com/open-telemetry/semantic-conventions/pull/1422
+ - rename_metrics:
+ messaging.client.published.messages: messaging.client.sent.messages
+ 1.27.0:
+ all:
+ changes:
+ # https://github.com/open-telemetry/semantic-conventions/pull/1216
+ - rename_attributes:
+ attribute_map:
+ tls.client.server_name: server.address
+ # https://github.com/open-telemetry/semantic-conventions/pull/1075
+ - rename_attributes:
+ attribute_map:
+ deployment.environment: deployment.environment.name
+ # https://github.com/open-telemetry/semantic-conventions/pull/1245
+ - rename_attributes:
+ attribute_map:
+ messaging.kafka.message.offset: messaging.kafka.offset
+ # https://github.com/open-telemetry/semantic-conventions/pull/815
+ - rename_attributes:
+ attribute_map:
+ messaging.kafka.consumer.group: messaging.consumer.group.name
+ messaging.rocketmq.client_group: messaging.consumer.group.name
+ messaging.eventhubs.consumer.group: messaging.consumer.group.name
+ messaging.servicebus.destination.subscription_name: messaging.destination.subscription.name
+ # https://github.com/open-telemetry/semantic-conventions/pull/1200
+ - rename_attributes:
+ attribute_map:
+ gen_ai.usage.completion_tokens: gen_ai.usage.output_tokens
+ gen_ai.usage.prompt_tokens: gen_ai.usage.input_tokens
+ spans:
+ changes:
+ # https://github.com/open-telemetry/semantic-conventions/pull/1002
+ - rename_attributes:
+ attribute_map:
+ db.elasticsearch.cluster.name: db.namespace
+ metrics:
+ changes:
+ # https://github.com/open-telemetry/semantic-conventions/pull/1125
+ - rename_attributes:
+ attribute_map:
+ db.client.connections.state: db.client.connection.state
+ apply_to_metrics:
+ - db.client.connection.count
+ - rename_attributes:
+ attribute_map:
+ db.client.connections.pool.name: db.client.connection.pool.name
+ apply_to_metrics:
+ - db.client.connection.count
+ - db.client.connection.idle.max
+ - db.client.connection.idle.min
+ - db.client.connection.max
+ - db.client.connection.pending_requests
+ - db.client.connection.timeouts
+ - db.client.connection.create_time
+ - db.client.connection.wait_time
+ - db.client.connection.use_time
+ # https://github.com/open-telemetry/semantic-conventions/pull/1006
+ - rename_metrics:
+ messaging.publish.messages: messaging.client.published.messages
+ # https://github.com/open-telemetry/semantic-conventions/pull/1026
+ - rename_attributes:
+ attribute_map:
+ system.cpu.state: cpu.mode
+ process.cpu.state: cpu.mode
+ container.cpu.state: cpu.mode
+ apply_to_metrics:
+ - system.cpu.time
+ - system.cpu.utilization
+ - process.cpu.time
+ - process.cpu.utilization
+ - container.cpu.time
+ # https://github.com/open-telemetry/semantic-conventions/pull/1265
+ - rename_metrics:
+ jvm.buffer.memory.usage: jvm.buffer.memory.used
+ 1.26.0:
+ metrics:
+ changes:
+ # https://github.com/open-telemetry/semantic-conventions/pull/966
+ - rename_metrics:
+ db.client.connections.usage: db.client.connection.count
+ db.client.connections.idle.max: db.client.connection.idle.max
+ db.client.connections.idle.min: db.client.connection.idle.min
+ db.client.connections.max: db.client.connection.max
+ db.client.connections.pending_requests: db.client.connection.pending_requests
+ db.client.connections.timeouts: db.client.connection.timeouts
+ # https://github.com/open-telemetry/semantic-conventions/pull/948
+ - rename_attributes:
+ attribute_map:
+ messaging.client_id: messaging.client.id
+ # https://github.com/open-telemetry/semantic-conventions/pull/909
+ - rename_attributes:
+ attribute_map:
+ state: db.client.connections.state
+ apply_to_metrics:
+ - db.client.connections.usage
+ - rename_attributes:
+ attribute_map:
+ pool.name: db.client.connections.pool.name
+ apply_to_metrics:
+ - db.client.connections.usage
+ - db.client.connections.idle.max
+ - db.client.connections.idle.min
+ - db.client.connections.max
+ - db.client.connections.pending_requests
+ - db.client.connections.timeouts
+ - db.client.connections.create_time
+ - db.client.connections.wait_time
+ - db.client.connections.use_time
+ all:
+ changes:
+ # https://github:com/open-telemetry/semantic-conventions/pull/731/
+ - rename_attributes:
+ attribute_map:
+ enduser.id: user.id
+
+ 1.25.0:
+ spans:
+ changes:
+ # https://github.com/open-telemetry/semantic-conventions/pull/911
+ - rename_attributes:
+ attribute_map:
+ db.name: db.namespace
+ # https://github.com/open-telemetry/semantic-conventions/pull/870
+ - rename_attributes:
+ attribute_map:
+ db.sql.table: db.collection.name
+ db.mongodb.collection: db.collection.name
+ db.cosmosdb.container: db.collection.name
+ db.cassandra.table: db.collection.name
+ # https://github.com/open-telemetry/semantic-conventions/pull/798
+ - rename_attributes:
+ attribute_map:
+ messaging.kafka.destination.partition: messaging.destination.partition.id
+ # https://github.com/open-telemetry/semantic-conventions/pull/875
+ - rename_attributes:
+ attribute_map:
+ db.operation: db.operation.name
+ # https://github.com/open-telemetry/semantic-conventions/pull/913
+ - rename_attributes:
+ attribute_map:
+ messaging.operation: messaging.operation.type
+ # https://github.com/open-telemetry/semantic-conventions/pull/866
+ - rename_attributes:
+ attribute_map:
+ db.statement: db.query.text
+ metrics:
+ changes:
+ # https://github.com/open-telemetry/semantic-conventions/pull/484
+ - rename_attributes:
+ attribute_map:
+ system.processes.status: system.process.status
+ apply_to_metrics:
+ - system.processes.count
+ - rename_metrics:
+ system.processes.count: system.process.count
+ system.processes.created: system.process.created
+ # https://github.com/open-telemetry/semantic-conventions/pull/625
+ - rename_attributes:
+ attribute_map:
+ container.labels: container.label
+ k8s.pod.labels: k8s.pod.label
+ # https://github.com/open-telemetry/semantic-conventions/pull/330
+ - rename_metrics:
+ process.threads: process.thread.count
+ process.open_file_descriptors: process.open_file_descriptor.count
+ - rename_attributes:
+ attribute_map:
+ state: process.cpu.state
+ apply_to_metrics:
+ - process.cpu.time
+ - process.cpu.utilization
+ - rename_attributes:
+ attribute_map:
+ direction: disk.io.direction
+ apply_to_metrics:
+ - process.disk.io
+ - rename_attributes:
+ attribute_map:
+ type: process.context_switch_type
+ apply_to_metrics:
+ - process.context_switches
+ - rename_attributes:
+ attribute_map:
+ direction: network.io.direction
+ apply_to_metrics:
+ - process.network.io
+ - rename_attributes:
+ attribute_map:
+ type: process.paging.fault_type
+ apply_to_metrics:
+ - process.paging.faults
+ all:
+ changes:
+ # https://github.com/open-telemetry/semantic-conventions/pull/854
+ - rename_attributes:
+ attribute_map:
+ message.type: rpc.message.type
+ message.id: rpc.message.id
+ message.compressed_size: rpc.message.compressed_size
+ message.uncompressed_size: rpc.message.uncompressed_size
+
+ 1.24.0:
+ metrics:
+ changes:
+ # https://github.com/open-telemetry/semantic-conventions/pull/536
+ - rename_metrics:
+ jvm.memory.usage: jvm.memory.used
+ jvm.memory.usage_after_last_gc: jvm.memory.used_after_last_gc
+ # https://github.com/open-telemetry/semantic-conventions/pull/530
+ - rename_attributes:
+ attribute_map:
+ system.network.io.direction: network.io.direction
+ system.disk.io.direction: disk.io.direction
+ 1.23.1:
+ 1.23.0:
+ metrics:
+ changes:
+ # https://github.com/open-telemetry/semantic-conventions/pull/20
+ - rename_attributes:
+ attribute_map:
+ thread.daemon: jvm.thread.daemon
+ apply_to_metrics:
+ - jvm.thread.count
+ 1.22.0:
+ spans:
+ changes:
+ # https://github.com/open-telemetry/semantic-conventions/pull/229
+ - rename_attributes:
+ attribute_map:
+ messaging.message.payload_size_bytes: messaging.message.body.size
+ # https://github.com/open-telemetry/opentelemetry-specification/pull/374
+ - rename_attributes:
+ attribute_map:
+ http.resend_count: http.request.resend_count
+ metrics:
+ changes:
+ # https://github.com/open-telemetry/semantic-conventions/pull/224
+ - rename_metrics:
+ http.client.duration: http.client.request.duration
+ http.server.duration: http.server.request.duration
+ # https://github.com/open-telemetry/semantic-conventions/pull/241
+ - rename_metrics:
+ process.runtime.jvm.memory.usage: jvm.memory.usage
+ process.runtime.jvm.memory.committed: jvm.memory.committed
+ process.runtime.jvm.memory.limit: jvm.memory.limit
+ process.runtime.jvm.memory.usage_after_last_gc: jvm.memory.usage_after_last_gc
+ process.runtime.jvm.gc.duration: jvm.gc.duration
+ # also https://github.com/open-telemetry/semantic-conventions/pull/252
+ process.runtime.jvm.threads.count: jvm.thread.count
+ # also https://github.com/open-telemetry/semantic-conventions/pull/252
+ process.runtime.jvm.classes.loaded: jvm.class.loaded
+ # also https://github.com/open-telemetry/semantic-conventions/pull/252
+ process.runtime.jvm.classes.unloaded: jvm.class.unloaded
+ # also https://github.com/open-telemetry/semantic-conventions/pull/252
+ # and https://github.com/open-telemetry/semantic-conventions/pull/60
+ process.runtime.jvm.classes.current_loaded: jvm.class.count
+ process.runtime.jvm.cpu.time: jvm.cpu.time
+ process.runtime.jvm.cpu.recent_utilization: jvm.cpu.recent_utilization
+ process.runtime.jvm.memory.init: jvm.memory.init
+ process.runtime.jvm.system.cpu.utilization: jvm.system.cpu.utilization
+ process.runtime.jvm.system.cpu.load_1m: jvm.system.cpu.load_1m
+ # https://github.com/open-telemetry/semantic-conventions/pull/253
+ process.runtime.jvm.buffer.usage: jvm.buffer.memory.usage
+ # https://github.com/open-telemetry/semantic-conventions/pull/253
+ process.runtime.jvm.buffer.limit: jvm.buffer.memory.limit
+ process.runtime.jvm.buffer.count: jvm.buffer.count
+ # https://github.com/open-telemetry/semantic-conventions/pull/20
+ - rename_attributes:
+ attribute_map:
+ type: jvm.memory.type
+ pool: jvm.memory.pool.name
+ apply_to_metrics:
+ - jvm.memory.usage
+ - jvm.memory.committed
+ - jvm.memory.limit
+ - jvm.memory.usage_after_last_gc
+ - jvm.memory.init
+ - rename_attributes:
+ attribute_map:
+ name: jvm.gc.name
+ action: jvm.gc.action
+ apply_to_metrics:
+ - jvm.gc.duration
+ - rename_attributes:
+ attribute_map:
+ daemon: thread.daemon
+ apply_to_metrics:
+ - jvm.threads.count
+ - rename_attributes:
+ attribute_map:
+ pool: jvm.buffer.pool.name
+ apply_to_metrics:
+ - jvm.buffer.memory.usage
+ - jvm.buffer.memory.limit
+ - jvm.buffer.count
+ # https://github.com/open-telemetry/semantic-conventions/pull/89
+ - rename_attributes:
+ attribute_map:
+ state: system.cpu.state
+ cpu: system.cpu.logical_number
+ apply_to_metrics:
+ - system.cpu.time
+ - system.cpu.utilization
+ - rename_attributes:
+ attribute_map:
+ state: system.memory.state
+ apply_to_metrics:
+ - system.memory.usage
+ - system.memory.utilization
+ - rename_attributes:
+ attribute_map:
+ state: system.paging.state
+ apply_to_metrics:
+ - system.paging.usage
+ - system.paging.utilization
+ - rename_attributes:
+ attribute_map:
+ type: system.paging.type
+ direction: system.paging.direction
+ apply_to_metrics:
+ - system.paging.faults
+ - system.paging.operations
+ - rename_attributes:
+ attribute_map:
+ device: system.device
+ direction: system.disk.direction
+ apply_to_metrics:
+ - system.disk.io
+ - system.disk.operations
+ - system.disk.io_time
+ - system.disk.operation_time
+ - system.disk.merged
+ - rename_attributes:
+ attribute_map:
+ device: system.device
+ state: system.filesystem.state
+ type: system.filesystem.type
+ mode: system.filesystem.mode
+ mountpoint: system.filesystem.mountpoint
+ apply_to_metrics:
+ - system.filesystem.usage
+ - system.filesystem.utilization
+ - rename_attributes:
+ attribute_map:
+ device: system.device
+ direction: system.network.direction
+ protocol: network.protocol
+ state: system.network.state
+ apply_to_metrics:
+ - system.network.dropped
+ - system.network.packets
+ - system.network.errors
+ - system.network.io
+ - system.network.connections
+ - rename_attributes:
+ attribute_map:
+ status: system.processes.status
+ apply_to_metrics:
+ - system.processes.count
+ # https://github.com/open-telemetry/semantic-conventions/pull/247
+ - rename_metrics:
+ http.server.request.size: http.server.request.body.size
+ http.server.response.size: http.server.response.body.size
+ resources:
+ changes:
+ # https://github.com/open-telemetry/semantic-conventions/pull/178
+ - rename_attributes:
+ attribute_map:
+ telemetry.auto.version: telemetry.distro.version
+ 1.21.0:
+ spans:
+ changes:
+ # https://github.com/open-telemetry/opentelemetry-specification/pull/3336
+ - rename_attributes:
+ attribute_map:
+ messaging.kafka.client_id: messaging.client_id
+ messaging.rocketmq.client_id: messaging.client_id
+ # https://github.com/open-telemetry/opentelemetry-specification/pull/3402
+ - rename_attributes:
+ attribute_map:
+ # net.peer.(name|port) attributes were usually populated on client side
+ # so they should be usually translated to server.(address|port)
+ # net.host.* attributes were only populated on server side
+ net.host.name: server.address
+ net.host.port: server.port
+ # was only populated on client side
+ net.sock.peer.name: server.socket.domain
+ # net.sock.peer.(addr|port) mapping is not possible
+ # since they applied to both client and server side
+ # were only populated on server side
+ net.sock.host.addr: server.socket.address
+ net.sock.host.port: server.socket.port
+ http.client_ip: client.address
+ # https://github.com/open-telemetry/opentelemetry-specification/pull/3426
+ - rename_attributes:
+ attribute_map:
+ net.protocol.name: network.protocol.name
+ net.protocol.version: network.protocol.version
+ net.host.connection.type: network.connection.type
+ net.host.connection.subtype: network.connection.subtype
+ net.host.carrier.name: network.carrier.name
+ net.host.carrier.mcc: network.carrier.mcc
+ net.host.carrier.mnc: network.carrier.mnc
+ net.host.carrier.icc: network.carrier.icc
+ # https://github.com/open-telemetry/opentelemetry-specification/pull/3355
+ - rename_attributes:
+ attribute_map:
+ http.method: http.request.method
+ http.status_code: http.response.status_code
+ http.scheme: url.scheme
+ http.url: url.full
+ http.request_content_length: http.request.body.size
+ http.response_content_length: http.response.body.size
+ metrics:
+ changes:
+ # https://github.com/open-telemetry/semantic-conventions/pull/53
+ - rename_metrics:
+ process.runtime.jvm.cpu.utilization: process.runtime.jvm.cpu.recent_utilization
+ 1.20.0:
+ spans:
+ changes:
+ # https://github.com/open-telemetry/opentelemetry-specification/pull/3272
+ - rename_attributes:
+ attribute_map:
+ net.app.protocol.name: net.protocol.name
+ net.app.protocol.version: net.protocol.version
+ 1.19.0:
+ spans:
+ changes:
+ # https://github.com/open-telemetry/opentelemetry-specification/pull/3209
+ - 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
+ # https://github.com/open-telemetry/opentelemetry-specification/pull/3190
+ - rename_attributes:
+ attribute_map:
+ http.user_agent: user_agent.original
+ resources:
+ changes:
+ # https://github.com/open-telemetry/opentelemetry-specification/pull/3190
+ - rename_attributes:
+ attribute_map:
+ browser.user_agent: user_agent.original
+ 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 176532d4a2e0d7f3c3777d0dad355c38118b50dc Mon Sep 17 00:00:00 2001
From: Liudmila Molkova
Date: Mon, 2 Dec 2024 11:04:28 -0800
Subject: [PATCH 27/32] Fix event policy check broken after 1.29.0 release
(#1641)
---
policies/compatibility.rego | 13 ++++++-------
policies_test/compatibility_test.rego | 24 ++++++++++++++++++++++++
2 files changed, 30 insertions(+), 7 deletions(-)
diff --git a/policies/compatibility.rego b/policies/compatibility.rego
index 31b391fe48..f8483ca4b3 100644
--- a/policies/compatibility.rego
+++ b/policies/compatibility.rego
@@ -48,7 +48,7 @@ baseline_events := [ g |
]
registry_events := [g |
some g in data.semconv.groups
- g.type == "events"
+ g.type == "event"
]
registry_event_names := { g.name | some g in registry_events }
@@ -236,11 +236,11 @@ deny contains back_comp_violation(description, group_id, attr.name) if {
# Rule: Detect Removed Metrics
#
# This rule checks for stable metrics that existed in the baseline registry
-# but are no longer present in the current registry. Removing attributes
+# but are no longer present in the current registry. Removing metrics
# is considered a backward compatibility violation.
#
-# In other words, we do not allow the removal of an attribute once added
-# to the registry. It must exist SOMEWHERE in a group, but may be deprecated.
+# In other words, we do not allow the removal of an metrics once added
+# to semantic conventions. They, however, may be deprecated.
deny contains back_comp_violation(description, group_id, "") if {
# Find data we need to enforce
some metric in baseline_metrics
@@ -366,7 +366,7 @@ deny contains back_comp_violation(description, group_id, "") if {
# is considered a backward compatibility violation.
#
# In other words, we do not allow the removal of a resource once added
-# to the registry. It must exist SOMEWHERE, but may be deprecated.
+# to semantic conventions. They, however, may be deprecated.
deny contains back_comp_violation(description, group_id, "") if {
# Find data we need to enforce
some resource in baseline_resources
@@ -432,11 +432,10 @@ deny contains back_comp_violation(description, group_id, "") if {
# is considered a backward compatibility violation.
#
# In other words, we do not allow the removal of a events once added
-# to the registry. It must exist SOMEWHERE, but may be deprecated.
+# to semantic conventions. They, however, may be deprecated.
deny contains back_comp_violation(description, group_id, "") if {
# Find data we need to enforce
some event in baseline_events
- event.stability == "stable" # remove after https://github.com/open-telemetry/semantic-conventions/pull/1512 is merged
# Enforce the policy
not registry_event_names[event.name]
diff --git a/policies_test/compatibility_test.rego b/policies_test/compatibility_test.rego
index 92ee2f2933..5976e02c54 100644
--- a/policies_test/compatibility_test.rego
+++ b/policies_test/compatibility_test.rego
@@ -679,6 +679,30 @@ test_removed_resources if {
}
}
+# Check that events cannot be removed.
+test_removed_events if {
+ count(deny) > 0 with data.semconv as {
+ "baseline_groups": [{
+ "id": "event.test.missing",
+ "type": "event",
+ "name": "test.missing"
+ }],
+ }
+ count(deny) == 0 with data.semconv as {
+ "baseline_groups": [{
+ "id": "event.test.deprecated",
+ "type": "event",
+ "name": "test.deprecated",
+ }],
+ "groups": [{
+ "id": "event.test.deprecated",
+ "type": "event",
+ "name": "test.deprecated",
+ "deprecated": "use `test` instead",
+ }]
+ }
+}
+
# Check that Stable resources cannot become unstable
test_resource_stability_change if {
count(deny) > 0 with data.semconv as {
From 123dd9348998c829d2471178a5ca127d4ab72dd1 Mon Sep 17 00:00:00 2001
From: Liudmila Molkova
Date: Mon, 2 Dec 2024 13:35:47 -0800
Subject: [PATCH 28/32] Relax collision detection policy to allow collisions
between deprecated namespaces and attributes (and vice-versa) (#1642)
---
policies/attribute_name_collisions.rego | 18 +++++++++++++-----
.../attribute_name_collisions_test.rego | 12 ++++++++++++
2 files changed, 25 insertions(+), 5 deletions(-)
diff --git a/policies/attribute_name_collisions.rego b/policies/attribute_name_collisions.rego
index c52f0267fc..0aa7bb506e 100644
--- a/policies/attribute_name_collisions.rego
+++ b/policies/attribute_name_collisions.rego
@@ -6,7 +6,7 @@ import rego.v1
attribute_names := { obj |
group := input.groups[_];
attr := group.attributes[_];
- obj := { "name": attr.name, "const_name": to_const_name(attr.name), "namespace_prefix": to_namespace_prefix(attr.name) }
+ obj := { "name": attr.name, "const_name": to_const_name(attr.name), "namespace_prefix": to_namespace_prefix(attr.name), "deprecated": is_property_set(attr, "deprecated") }
}
# check that attribute constant names do not collide
@@ -29,11 +29,17 @@ deny contains attr_registry_collision(description, name) if {
# check that attribute names do not collide with namespaces
deny contains attr_registry_collision(description, name) if {
some i
+
+ # ignore deprecated attributes
+ not attribute_names[i].deprecated
+
name := attribute_names[i].name
prefix := attribute_names[i].namespace_prefix
- not excluded_namespace_collisions[name]
+
collisions := [other.name |
other := attribute_names[_]
+ not other.deprecated
+
other.name != name
startswith(other.name, prefix)
]
@@ -72,7 +78,11 @@ to_const_name(name) = const_name if {
const_name := replace(name, ".", "_")
}
-# These lists contain exceptions for existing collisions that were introduced unintentionally.
+is_property_set(obj, property) = true if {
+ obj[property] != null
+} else = false
+
+# This list contains exceptions for existing collisions that were introduced unintentionally.
# We'll have a way to specify how collision resolution happens in the schema -
# see phase 2 in https://github.com/open-telemetry/semantic-conventions/issues/1118#issuecomment-2173803006
# For now we'll exclude existing collisions from the checks.
@@ -80,5 +90,3 @@ to_const_name(name) = const_name if {
# DO NOT ADD ATTRIBUTES TO THIS LIST
excluded_const_collisions := {"messaging.client_id"}
-# DO NOT ADD ATTRIBUTES TO THIS LIST
-excluded_namespace_collisions := {"messaging.operation", "db.operation", "deployment.environment"}
diff --git a/policies_test/attribute_name_collisions_test.rego b/policies_test/attribute_name_collisions_test.rego
index b86e79fece..2d09beb7c4 100644
--- a/policies_test/attribute_name_collisions_test.rego
+++ b/policies_test/attribute_name_collisions_test.rego
@@ -17,3 +17,15 @@ test_fails_on_namespace_collision if {
]}
count(deny) == 1 with input as collision
}
+
+test_does_not_fail_on_deprecated_namespace_collision if {
+ collision := {"groups": [
+ {"id": "test1", "attributes": [{"name": "test.namespace.id"}]},
+ {"id": "test2", "attributes": [{"name": "test.namespace", "deprecated": "replaced by foo.bar.baz"}]},
+
+ {"id": "test3", "attributes": [{"name": "another_test.namespace.id", "deprecated": "replaced by another_test.namespace"}]},
+ {"id": "test4", "attributes": [{"name": "another_test.namespace"}]},
+ ]}
+ count(deny) == 0 with input as collision
+}
+
From 2d34907ac6d08735060f19c759771dd37ff36ee7 Mon Sep 17 00:00:00 2001
From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Date: Tue, 3 Dec 2024 10:38:34 +0100
Subject: [PATCH 29/32] Include PR/Issue links in the changelog (#1630)
---
.chloggen/CHANGELOG.tmpl | 72 ++++++++++++++++++++++++++++++++++++++++
.chloggen/config.yaml | 3 ++
2 files changed, 75 insertions(+)
create mode 100644 .chloggen/CHANGELOG.tmpl
diff --git a/.chloggen/CHANGELOG.tmpl b/.chloggen/CHANGELOG.tmpl
new file mode 100644
index 0000000000..416959e205
--- /dev/null
+++ b/.chloggen/CHANGELOG.tmpl
@@ -0,0 +1,72 @@
+{{/*
+Based on the default template:
+https://github.com/open-telemetry/opentelemetry-go-build-tools/blob/v0.15.0/chloggen/internal/chlog/summary.tmpl
+*/}}
+{{- define "entry" -}}
+- `{{ .Component }}`: {{ .Note }} (
+{{- range $i, $issue := .Issues }}
+{{- if $i }}, {{ end -}}
+[#{{ $issue }}](https://github.com/open-telemetry/semantic-conventions/issues/{{ $issue }})
+{{- end -}}
+)
+
+{{- if .SubText }}
+{{ .SubText | indent 2 }}
+{{- end }}
+{{- end }}
+## {{ .Version }}
+
+{{- if .BreakingChanges }}
+
+### 🛑 Breaking changes 🛑
+
+{{- range $i, $change := .BreakingChanges }}
+{{- if eq $i 0}}
+{{end}}
+{{ template "entry" $change }}
+{{- end }}
+{{- end }}
+
+{{- if .Deprecations }}
+
+### 🚩 Deprecations 🚩
+
+{{- range $i, $change := .Deprecations }}
+{{- if eq $i 0}}
+{{end}}
+{{ template "entry" $change }}
+{{- end }}
+{{- end }}
+
+{{- if .NewComponents }}
+
+### 🚀 New components 🚀
+
+{{- range $i, $change := .NewComponents }}
+{{- if eq $i 0}}
+{{end}}
+{{ template "entry" $change }}
+{{- end }}
+{{- end }}
+
+{{- if .Enhancements }}
+
+### 💡 Enhancements 💡
+
+{{- range $i, $change := .Enhancements }}
+{{- if eq $i 0}}
+{{end}}
+{{ template "entry" $change }}
+{{- end }}
+{{- end }}
+
+{{- if .BugFixes }}
+
+### 🧰 Bug fixes 🧰
+
+{{- range $i, $change := .BugFixes }}
+{{- if eq $i 0}}
+{{end}}
+{{ template "entry" $change }}
+{{- end }}
+{{- end }}
diff --git a/.chloggen/config.yaml b/.chloggen/config.yaml
index 411f32d3a5..f600745253 100644
--- a/.chloggen/config.yaml
+++ b/.chloggen/config.yaml
@@ -22,3 +22,6 @@ change_logs:
# If 'change_logs' is specified in this file, and no value is specified for 'default_change_logs',
# then 'change_logs' MUST be specified in every entry file.
default_change_logs: [user]
+
+# Custom template for the changelog that include links for the issue/PRs
+summary_template: .chloggen/CHANGELOG.tmpl
From c2f983d19973dda873b712f55a78e4d4e70f5f17 Mon Sep 17 00:00:00 2001
From: Liudmila Molkova
Date: Tue, 3 Dec 2024 08:38:37 -0800
Subject: [PATCH 30/32] Update approvers (#1643)
Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com>
---
README.md | 9 ++++++---
1 file changed, 6 insertions(+), 3 deletions(-)
diff --git a/README.md b/README.md
index 8fbcb03ac5..ddba49fe5f 100644
--- a/README.md
+++ b/README.md
@@ -19,10 +19,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md)
Approvers ([@open-telemetry/specs-semconv-approvers](https://github.com/orgs/open-telemetry/teams/specs-semconv-approvers)):
- [Alexandra Konrad](https://github.com/trisch-me), Elastic
-- [Christian Neumüller](https://github.com/Oberon00), Dynatrace
- [Daniel Dyla](https://github.com/dyladan), Dynatrace
-- [James Moessis](https://github.com/jamesmoessis), Atlassian
-- [Sean Marciniak](https://github.com/MovieStoreGuy), Atlassian
- [Ted Young](https://github.com/tedsuo), Lightstep
_Find more about the approver role in [community repository](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#approver)._
@@ -37,6 +34,12 @@ Maintainers ([@open-telemetry/specs-semconv-maintainers](https://github.com/orgs
- [Liudmila Molkova](https://github.com/lmolkova), Microsoft
- [Trask Stalnaker](https://github.com/trask), Microsoft
+Emeritus Approvers:
+
+- [Christian Neumüller](https://github.com/Oberon00)
+- [James Moessis](https://github.com/jamesmoessis)
+- [Sean Marciniak](https://github.com/MovieStoreGuy)
+
Emeritus Maintainers:
- [Reiley Yang](https://github.com/reyang)
From c8024bf2429cc0f40097e44556b3f2e5668f7cb8 Mon Sep 17 00:00:00 2001
From: Adriel Perkins
Date: Tue, 3 Dec 2024 13:46:56 -0500
Subject: [PATCH 31/32] [vcs] Adds `vcs.repository.name` attribute and updates
`vcs.repository.url.full` to be represented consistently. (#1608)
Co-authored-by: Liudmila Molkova
Co-authored-by: Trask Stalnaker
---
.chloggen/vcs-1254.yaml | 25 +++++++++++
docs/attributes-registry/vcs.md | 10 ++++-
docs/cicd/cicd-metrics.md | 80 +++++++++++++++++++++++++++++----
model/vcs/metrics.yaml | 16 +++++++
model/vcs/registry.yaml | 25 +++++++++--
5 files changed, 144 insertions(+), 12 deletions(-)
create mode 100755 .chloggen/vcs-1254.yaml
diff --git a/.chloggen/vcs-1254.yaml b/.chloggen/vcs-1254.yaml
new file mode 100755
index 0000000000..bbb88ac423
--- /dev/null
+++ b/.chloggen/vcs-1254.yaml
@@ -0,0 +1,25 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: vcs
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: |
+ Adds `vcs.repository.name` attribute to registry and update
+ `vcs.repository.url.full` description for consistent representation. Updates
+ the VCS metrics to include `vcs.repository.name` as a recommended attribute.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1254, 1453]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/docs/attributes-registry/vcs.md b/docs/attributes-registry/vcs.md
index b418b16e83..b17426a93c 100644
--- a/docs/attributes-registry/vcs.md
+++ b/docs/attributes-registry/vcs.md
@@ -26,7 +26,8 @@ This group defines the attributes for [Version Control Systems (VCS)](https://wi
| `vcs.ref.head.revision` | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [2] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` |  |
| `vcs.ref.head.type` | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` |  |
| `vcs.ref.type` | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` |  |
-| `vcs.repository.url.full` | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` |  |
+| `vcs.repository.name` | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [3] | `semantic-conventions`; `my-cool-repo` |  |
+| `vcs.repository.url.full` | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [4] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` |  |
| `vcs.revision_delta.direction` | string | The type of revision comparison. | `ahead`; `behind` |  |
**[1] `vcs.ref.base.revision`:** The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf),
@@ -49,6 +50,13 @@ it is identical to the `ref.head.name`, it SHOULD still be included. It is
up to the implementer to decide which value to set as the revision
based on the VCS system and situational context.
+**[3] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same
+repository if collecting telemetry across multiple orgs or groups in
+the same backends.
+
+**[4] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include
+the `.git` extension.
+
---
`vcs.change.state` 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/docs/cicd/cicd-metrics.md b/docs/cicd/cicd-metrics.md
index 621ba0bbc8..687eb76e43 100644
--- a/docs/cicd/cicd-metrics.md
+++ b/docs/cicd/cicd-metrics.md
@@ -48,7 +48,15 @@ This metric is [recommended][MetricRecommended].
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`vcs.change.state`](/docs/attributes-registry/vcs.md) | string | The state of the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | `Required` |  |
-| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [1] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [2] | `semantic-conventions`; `my-cool-repo` | `Recommended` |  |
+
+**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include
+the `.git` extension.
+
+**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same
+repository if collecting telemetry across multiple orgs or groups in
+the same backends.
---
@@ -85,7 +93,15 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`vcs.change.state`](/docs/attributes-registry/vcs.md) | string | The state of the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | `Required` |  |
| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` |  |
-| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [1] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [2] | `semantic-conventions`; `my-cool-repo` | `Recommended` |  |
+
+**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include
+the `.git` extension.
+
+**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same
+repository if collecting telemetry across multiple orgs or groups in
+the same backends.
---
@@ -121,7 +137,15 @@ This metric is [recommended][MetricRecommended].
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` |  |
-| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [1] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [2] | `semantic-conventions`; `my-cool-repo` | `Recommended` |  |
+
+**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include
+the `.git` extension.
+
+**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same
+repository if collecting telemetry across multiple orgs or groups in
+the same backends.
@@ -166,7 +190,15 @@ This metric is [recommended][MetricRecommended].
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`vcs.ref.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` |  |
-| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [1] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [2] | `semantic-conventions`; `my-cool-repo` | `Recommended` |  |
+
+**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include
+the `.git` extension.
+
+**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same
+repository if collecting telemetry across multiple orgs or groups in
+the same backends.
---
@@ -208,8 +240,16 @@ If number of lines added/removed should be calculated from the start of time, th
| [`vcs.ref.base.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` |  |
| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` |  |
| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` |  |
-| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [1] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
| [`vcs.change.id`](/docs/attributes-registry/vcs.md) | string | The ID of the change (pull request/merge request/changelist) if applicable. This is usually a unique (within repository) identifier generated by the VCS system. | `123` | `Conditionally Required` if a change is associate with the ref. |  |
+| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [2] | `semantic-conventions`; `my-cool-repo` | `Recommended` |  |
+
+**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include
+the `.git` extension.
+
+**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same
+repository if collecting telemetry across multiple orgs or groups in
+the same backends.
---
@@ -267,9 +307,17 @@ instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers)
| [`vcs.ref.base.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` |  |
| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` |  |
| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` |  |
-| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [1] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
| [`vcs.revision_delta.direction`](/docs/attributes-registry/vcs.md) | string | The type of revision comparison. | `ahead`; `behind` | `Required` |  |
| [`vcs.change.id`](/docs/attributes-registry/vcs.md) | string | The ID of the change (pull request/merge request/changelist) if applicable. This is usually a unique (within repository) identifier generated by the VCS system. | `123` | `Conditionally Required` if a change is associate with the ref. |  |
+| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [2] | `semantic-conventions`; `my-cool-repo` | `Recommended` |  |
+
+**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include
+the `.git` extension.
+
+**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same
+repository if collecting telemetry across multiple orgs or groups in
+the same backends.
---
@@ -322,7 +370,15 @@ This metric is [recommended][MetricRecommended].
|---|---|---|---|---|---|
| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` |  |
| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` |  |
-| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [1] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [2] | `semantic-conventions`; `my-cool-repo` | `Recommended` |  |
+
+**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include
+the `.git` extension.
+
+**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same
+repository if collecting telemetry across multiple orgs or groups in
+the same backends.
---
@@ -355,7 +411,15 @@ This metric is [opt-in][MetricOptIn].
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [1] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` |  |
+| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [2] | `semantic-conventions`; `my-cool-repo` | `Recommended` |  |
+
+**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include
+the `.git` extension.
+
+**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same
+repository if collecting telemetry across multiple orgs or groups in
+the same backends.
diff --git a/model/vcs/metrics.yaml b/model/vcs/metrics.yaml
index e2e72f115f..9bb3118942 100644
--- a/model/vcs/metrics.yaml
+++ b/model/vcs/metrics.yaml
@@ -11,6 +11,8 @@ groups:
requirement_level: required
- ref: vcs.repository.url.full
requirement_level: required
+ - ref: vcs.repository.name
+ requirement_level: recommended
- id: metric.vcs.change.duration
type: metric
metric_name: vcs.change.duration
@@ -21,6 +23,8 @@ groups:
attributes:
- ref: vcs.repository.url.full
requirement_level: required
+ - ref: vcs.repository.name
+ requirement_level: recommended
- ref: vcs.ref.head.name
requirement_level: required
- ref: vcs.change.state
@@ -35,6 +39,8 @@ groups:
attributes:
- ref: vcs.repository.url.full
requirement_level: required
+ - ref: vcs.repository.name
+ requirement_level: recommended
- ref: vcs.ref.head.name
requirement_level: required
- id: metric.vcs.repository.count
@@ -55,6 +61,8 @@ groups:
attributes:
- ref: vcs.repository.url.full
requirement_level: required
+ - ref: vcs.repository.name
+ requirement_level: recommended
- ref: vcs.ref.type
requirement_level: required
- id: metric.vcs.ref.lines_delta
@@ -74,6 +82,8 @@ groups:
conditionally_required: if a change is associate with the ref.
- ref: vcs.repository.url.full
requirement_level: required
+ - ref: vcs.repository.name
+ requirement_level: recommended
- ref: vcs.ref.head.name
requirement_level: required
- ref: vcs.ref.head.type
@@ -100,6 +110,8 @@ groups:
conditionally_required: if a change is associate with the ref.
- ref: vcs.repository.url.full
requirement_level: required
+ - ref: vcs.repository.name
+ requirement_level: recommended
- ref: vcs.ref.head.name
requirement_level: required
- ref: vcs.ref.head.type
@@ -120,6 +132,8 @@ groups:
attributes:
- ref: vcs.repository.url.full
requirement_level: required
+ - ref: vcs.repository.name
+ requirement_level: recommended
- ref: vcs.ref.head.name
requirement_level: required
- ref: vcs.ref.head.type
@@ -134,3 +148,5 @@ groups:
attributes:
- ref: vcs.repository.url.full
requirement_level: required
+ - ref: vcs.repository.name
+ requirement_level: recommended
diff --git a/model/vcs/registry.yaml b/model/vcs/registry.yaml
index afe703ac53..8b61583e0b 100644
--- a/model/vcs/registry.yaml
+++ b/model/vcs/registry.yaml
@@ -9,14 +9,33 @@ groups:
type: string
stability: experimental
brief: >
- The [URL](https://wikipedia.org/wiki/URL) of the repository
- providing the complete address in order to locate and identify the
- repository.
+ The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.)
+ of the repository providing the complete HTTP(S) address in order to
+ locate and identify the repository through a browser.
+ note: |
+ In Git Version Control Systems, the canonical URL SHOULD NOT include
+ the `.git` extension.
examples:
[
"https://github.com/opentelemetry/open-telemetry-collector-contrib",
"https://gitlab.com/my-org/my-project/my-projects-project/repo",
]
+ - id: vcs.repository.name
+ type: string
+ stability: experimental
+ brief: >
+ The human readable name of the repository. It SHOULD NOT include any
+ additional identifier like Group/SubGroup in GitLab or organization
+ in GitHub.
+ note: |
+ Due to it only being the name, it can clash with forks of the same
+ repository if collecting telemetry across multiple orgs or groups in
+ the same backends.
+ examples:
+ [
+ "semantic-conventions",
+ "my-cool-repo",
+ ]
- id: vcs.ref.base.name
type: string
stability: experimental
From 41053b507998b6dc4effa22f657cea96ab5f8fe8 Mon Sep 17 00:00:00 2001
From: Steve Gordon
Date: Tue, 3 Dec 2024 20:39:24 +0000
Subject: [PATCH 32/32] Mark .NET runtime metrics as stable (#1609)
Co-authored-by: Liudmila Molkova
---
.chloggen/stable-dotnet-runtime-metrics.yaml | 22 +++++
docs/attributes-registry/dotnet.md | 12 +--
docs/runtime/dotnet-metrics.md | 86 ++++++++++----------
model/dotnet/registry.yaml | 12 +--
model/dotnet/runtime-metrics.yaml | 38 ++++-----
policies/group_stability.rego | 2 +
6 files changed, 98 insertions(+), 74 deletions(-)
create mode 100644 .chloggen/stable-dotnet-runtime-metrics.yaml
diff --git a/.chloggen/stable-dotnet-runtime-metrics.yaml b/.chloggen/stable-dotnet-runtime-metrics.yaml
new file mode 100644
index 0000000000..ac6b3135ec
--- /dev/null
+++ b/.chloggen/stable-dotnet-runtime-metrics.yaml
@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: dotnet
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Mark .NET runtime metrics as stable
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1602]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/docs/attributes-registry/dotnet.md b/docs/attributes-registry/dotnet.md
index 75acc35161..7f5208774a 100644
--- a/docs/attributes-registry/dotnet.md
+++ b/docs/attributes-registry/dotnet.md
@@ -12,7 +12,7 @@ This document defines .NET related attributes.
| Attribute | Type | Description | Examples | Stability |
|---|---|---|---|---|
-| `dotnet.gc.heap.generation` | string | Name of the garbage collector managed heap generation. | `gen0`; `gen1`; `gen2` |  |
+| `dotnet.gc.heap.generation` | string | Name of the garbage collector managed heap generation. | `gen0`; `gen1`; `gen2` |  |
---
@@ -20,8 +20,8 @@ This document defines .NET related attributes.
| Value | Description | Stability |
|---|---|---|
-| `gen0` | Generation 0 |  |
-| `gen1` | Generation 1 |  |
-| `gen2` | Generation 2 |  |
-| `loh` | Large Object Heap |  |
-| `poh` | Pinned Object Heap |  |
+| `gen0` | Generation 0 |  |
+| `gen1` | Generation 1 |  |
+| `gen2` | Generation 2 |  |
+| `loh` | Large Object Heap |  |
+| `poh` | Pinned Object Heap |  |
diff --git a/docs/runtime/dotnet-metrics.md b/docs/runtime/dotnet-metrics.md
index 00b0b40035..42189f33a8 100644
--- a/docs/runtime/dotnet-metrics.md
+++ b/docs/runtime/dotnet-metrics.md
@@ -4,7 +4,7 @@ linkTitle: .NET
# Semantic Conventions for .NET Common Language Runtime (CLR) Metrics
-**Status**: [Experimental][DocumentStatus]
+**Status**: [Stable][DocumentStatus]
This document describes semantic conventions for .NET CLR runtime metrics in OpenTelemetry.
@@ -41,7 +41,7 @@ This document describes semantic conventions for .NET CLR runtime metrics in Ope
## .NET CLR Process
-**Status**: [Experimental][DocumentStatus]
+**Status**: [Stable][DocumentStatus]
**Description:** .NET Common Language Runtime (CLR) metrics relating to the process, captured under the namespace `dotnet.process.*`.
@@ -60,7 +60,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.process.cpu.count` | UpDownCounter | `{cpu}` | The number of processors available to the process. [1] |  |
+| `dotnet.process.cpu.count` | UpDownCounter | `{cpu}` | The number of processors available to the process. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as accessing [`Environment.ProcessorCount`](https://learn.microsoft.com/dotnet/api/system.environment.processorcount).
@@ -83,7 +83,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.process.cpu.time` | Counter | `s` | CPU time used by the process. [1] |  |
+| `dotnet.process.cpu.time` | Counter | `s` | CPU time used by the process. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as accessing the corresponding processor time properties on [`System.Diagnostics.Process`](https://learn.microsoft.com/dotnet/api/system.diagnostics.process).
@@ -125,7 +125,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.process.memory.working_set` | UpDownCounter | `By` | The number of bytes of physical memory mapped to the process context. [1] |  |
+| `dotnet.process.memory.working_set` | UpDownCounter | `By` | The number of bytes of physical memory mapped to the process context. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as calling [`Environment.WorkingSet`](https://learn.microsoft.com/dotnet/api/system.environment.workingset).
@@ -137,7 +137,7 @@ This metric reports the same values as calling [`Environment.WorkingSet`](https:
## .NET CLR Garbage Collection
-**Status**: [Experimental][DocumentStatus]
+**Status**: [Stable][DocumentStatus]
**Description:** .NET Common Language Runtime (CLR) metrics relating to garbage collection, captured under the namespace `dotnet.gc.*`.
@@ -154,14 +154,14 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.gc.collections` | Counter | `{collection}` | The number of garbage collections that have occurred since the process has started. [1] |  |
+| `dotnet.gc.collections` | Counter | `{collection}` | The number of garbage collections that have occurred since the process has started. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric uses the [`GC.CollectionCount(int generation)`](https://learn.microsoft.com/dotnet/api/system.gc.collectioncount) API to calculate exclusive collections per generation.
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`dotnet.gc.heap.generation`](/docs/attributes-registry/dotnet.md) | string | Name of the garbage collector managed heap generation. | `gen0`; `gen1`; `gen2` | `Required` |  |
+| [`dotnet.gc.heap.generation`](/docs/attributes-registry/dotnet.md) | string | Name of the garbage collector managed heap generation. | `gen0`; `gen1`; `gen2` | `Required` |  |
---
@@ -169,11 +169,11 @@ This metric uses the [`GC.CollectionCount(int generation)`](https://learn.micros
| Value | Description | Stability |
|---|---|---|
-| `gen0` | Generation 0 |  |
-| `gen1` | Generation 1 |  |
-| `gen2` | Generation 2 |  |
-| `loh` | Large Object Heap |  |
-| `poh` | Pinned Object Heap |  |
+| `gen0` | Generation 0 |  |
+| `gen1` | Generation 1 |  |
+| `gen2` | Generation 2 |  |
+| `loh` | Large Object Heap |  |
+| `poh` | Pinned Object Heap |  |
@@ -193,7 +193,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.gc.heap.total_allocated` | Counter | `By` | The *approximate* number of bytes allocated on the managed GC heap since the process has started. The returned value does not include any native allocations. [1] |  |
+| `dotnet.gc.heap.total_allocated` | Counter | `By` | The *approximate* number of bytes allocated on the managed GC heap since the process has started. The returned value does not include any native allocations. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as calling [`GC.GetTotalAllocatedBytes()`](https://learn.microsoft.com/dotnet/api/system.gc.gettotalallocatedbytes).
@@ -216,7 +216,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.gc.last_collection.memory.committed_size` | UpDownCounter | `By` | The amount of committed virtual memory in use by the .NET GC, as observed during the latest garbage collection. [1] |  |
+| `dotnet.gc.last_collection.memory.committed_size` | UpDownCounter | `By` | The amount of committed virtual memory in use by the .NET GC, as observed during the latest garbage collection. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as calling [`GC.GetGCMemoryInfo().TotalCommittedBytes`](https://learn.microsoft.com/dotnet/api/system.gcmemoryinfo.totalcommittedbytes). Committed virtual memory may be larger than the heap size because it includes both memory for storing existing objects (the heap size) and some extra memory that is ready to handle newly allocated objects in the future.
@@ -239,14 +239,14 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.gc.last_collection.heap.size` | UpDownCounter | `By` | The managed GC heap size (including fragmentation), as observed during the latest garbage collection. [1] |  |
+| `dotnet.gc.last_collection.heap.size` | UpDownCounter | `By` | The managed GC heap size (including fragmentation), as observed during the latest garbage collection. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as calling [`GC.GetGCMemoryInfo().GenerationInfo.SizeAfterBytes`](https://learn.microsoft.com/dotnet/api/system.gcgenerationinfo.sizeafterbytes).
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`dotnet.gc.heap.generation`](/docs/attributes-registry/dotnet.md) | string | Name of the garbage collector managed heap generation. | `gen0`; `gen1`; `gen2` | `Required` |  |
+| [`dotnet.gc.heap.generation`](/docs/attributes-registry/dotnet.md) | string | Name of the garbage collector managed heap generation. | `gen0`; `gen1`; `gen2` | `Required` |  |
---
@@ -254,11 +254,11 @@ This metric reports the same values as calling [`GC.GetGCMemoryInfo().Generation
| Value | Description | Stability |
|---|---|---|
-| `gen0` | Generation 0 |  |
-| `gen1` | Generation 1 |  |
-| `gen2` | Generation 2 |  |
-| `loh` | Large Object Heap |  |
-| `poh` | Pinned Object Heap |  |
+| `gen0` | Generation 0 |  |
+| `gen1` | Generation 1 |  |
+| `gen2` | Generation 2 |  |
+| `loh` | Large Object Heap |  |
+| `poh` | Pinned Object Heap |  |
@@ -278,14 +278,14 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.gc.last_collection.heap.fragmentation.size` | UpDownCounter | `By` | The heap fragmentation, as observed during the latest garbage collection. [1] |  |
+| `dotnet.gc.last_collection.heap.fragmentation.size` | UpDownCounter | `By` | The heap fragmentation, as observed during the latest garbage collection. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as calling [`GC.GetGCMemoryInfo().GenerationInfo.FragmentationAfterBytes`](https://learn.microsoft.com/dotnet/api/system.gcgenerationinfo.fragmentationafterbytes).
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
-| [`dotnet.gc.heap.generation`](/docs/attributes-registry/dotnet.md) | string | Name of the garbage collector managed heap generation. | `gen0`; `gen1`; `gen2` | `Required` |  |
+| [`dotnet.gc.heap.generation`](/docs/attributes-registry/dotnet.md) | string | Name of the garbage collector managed heap generation. | `gen0`; `gen1`; `gen2` | `Required` |  |
---
@@ -293,11 +293,11 @@ This metric reports the same values as calling [`GC.GetGCMemoryInfo().Generation
| Value | Description | Stability |
|---|---|---|
-| `gen0` | Generation 0 |  |
-| `gen1` | Generation 1 |  |
-| `gen2` | Generation 2 |  |
-| `loh` | Large Object Heap |  |
-| `poh` | Pinned Object Heap |  |
+| `gen0` | Generation 0 |  |
+| `gen1` | Generation 1 |  |
+| `gen2` | Generation 2 |  |
+| `loh` | Large Object Heap |  |
+| `poh` | Pinned Object Heap |  |
@@ -317,7 +317,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.gc.pause.time` | Counter | `s` | The total amount of time paused in GC since the process has started. [1] |  |
+| `dotnet.gc.pause.time` | Counter | `s` | The total amount of time paused in GC since the process has started. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as calling [`GC.GetTotalPauseDuration()`](https://learn.microsoft.com/dotnet/api/system.gc.gettotalpauseduration).
@@ -329,7 +329,7 @@ This metric reports the same values as calling [`GC.GetTotalPauseDuration()`](ht
## .NET CLR Just-In-Time (JIT) Compiler
-**Status**: [Experimental][DocumentStatus]
+**Status**: [Stable][DocumentStatus]
**Description:** .NET Common Language Runtime (CLR) metrics relating to the Just-In-Time compiler, captured under the namespace `dotnet.jit.*`.
@@ -346,7 +346,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.jit.compiled_il.size` | Counter | `By` | Count of bytes of intermediate language that have been compiled since the process has started. [1] |  |
+| `dotnet.jit.compiled_il.size` | Counter | `By` | Count of bytes of intermediate language that have been compiled since the process has started. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as calling [`JitInfo.GetCompiledILBytes()`](https://learn.microsoft.com/dotnet/api/system.runtime.jitinfo.getcompiledilbytes).
@@ -369,7 +369,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.jit.compiled_methods` | Counter | `{method}` | The number of times the JIT compiler (re)compiled methods since the process has started. [1] |  |
+| `dotnet.jit.compiled_methods` | Counter | `{method}` | The number of times the JIT compiler (re)compiled methods since the process has started. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as calling [`JitInfo.GetCompiledMethodCount()`](https://learn.microsoft.com/dotnet/api/system.runtime.jitinfo.getcompiledmethodcount).
@@ -392,7 +392,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.jit.compilation.time` | Counter | `s` | The amount of time the JIT compiler has spent compiling methods since the process has started. [1] |  |
+| `dotnet.jit.compilation.time` | Counter | `s` | The amount of time the JIT compiler has spent compiling methods since the process has started. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as calling [`JitInfo.GetCompilationTime()`](https://learn.microsoft.com/dotnet/api/system.runtime.jitinfo.getcompilationtime).
@@ -404,7 +404,7 @@ This metric reports the same values as calling [`JitInfo.GetCompilationTime()`](
## .NET CLR Thread pool
-**Status**: [Experimental][DocumentStatus]
+**Status**: [Stable][DocumentStatus]
**Description:** .NET Common Language Runtime (CLR) metrics relating to the thread pool, captured under the namespace `dotnet.thread_pool.*`.
@@ -421,7 +421,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.thread_pool.thread.count` | UpDownCounter | `{thread}` | The number of thread pool threads that currently exist. [1] |  |
+| `dotnet.thread_pool.thread.count` | UpDownCounter | `{thread}` | The number of thread pool threads that currently exist. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as calling [`ThreadPool.ThreadCount`](https://learn.microsoft.com/dotnet/api/system.threading.threadpool.threadcount).
@@ -444,7 +444,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.thread_pool.work_item.count` | Counter | `{work_item}` | The number of work items that the thread pool has completed since the process has started. [1] |  |
+| `dotnet.thread_pool.work_item.count` | Counter | `{work_item}` | The number of work items that the thread pool has completed since the process has started. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as calling [`ThreadPool.CompletedWorkItemCount`](https://learn.microsoft.com/dotnet/api/system.threading.threadpool.completedworkitemcount).
@@ -467,7 +467,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.thread_pool.queue.length` | UpDownCounter | `{work_item}` | The number of work items that are currently queued to be processed by the thread pool. [1] |  |
+| `dotnet.thread_pool.queue.length` | UpDownCounter | `{work_item}` | The number of work items that are currently queued to be processed by the thread pool. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as calling [`ThreadPool.PendingWorkItemCount`](https://learn.microsoft.com/dotnet/api/system.threading.threadpool.pendingworkitemcount).
@@ -479,7 +479,7 @@ This metric reports the same values as calling [`ThreadPool.PendingWorkItemCount
## .NET CLR General
-**Status**: [Experimental][DocumentStatus]
+**Status**: [Stable][DocumentStatus]
**Description:** Other useful .NET Common Language Runtime (CLR) metrics.
@@ -496,7 +496,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.monitor.lock_contentions` | Counter | `{contention}` | The number of times there was contention when trying to acquire a monitor lock since the process has started. [1] |  |
+| `dotnet.monitor.lock_contentions` | Counter | `{contention}` | The number of times there was contention when trying to acquire a monitor lock since the process has started. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as calling [`Monitor.LockContentionCount`](https://learn.microsoft.com/dotnet/api/system.threading.monitor.lockcontentioncount).
@@ -519,7 +519,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.timer.count` | UpDownCounter | `{timer}` | The number of timer instances that are currently active. [1] |  |
+| `dotnet.timer.count` | UpDownCounter | `{timer}` | The number of timer instances that are currently active. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as calling [`Timer.ActiveCount`](https://learn.microsoft.com/dotnet/api/system.threading.timer.activecount).
@@ -542,7 +542,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.assembly.count` | UpDownCounter | `{assembly}` | The number of .NET assemblies that are currently loaded. [1] |  |
+| `dotnet.assembly.count` | UpDownCounter | `{assembly}` | The number of .NET assemblies that are currently loaded. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as calling [`AppDomain.CurrentDomain.GetAssemblies().Length`](https://learn.microsoft.com/dotnet/api/system.appdomain.getassemblies).
@@ -565,7 +565,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
-| `dotnet.exceptions` | Counter | `{exception}` | The number of exceptions that have been thrown in managed code. [1] |  |
+| `dotnet.exceptions` | Counter | `{exception}` | The number of exceptions that have been thrown in managed code. [1] |  |
**[1]:** Meter name: `System.Runtime`; Added in: .NET 9.0.
This metric reports the same values as counting calls to [`AppDomain.CurrentDomain.FirstChanceException`](https://learn.microsoft.com/dotnet/api/system.appdomain.firstchanceexception).
diff --git a/model/dotnet/registry.yaml b/model/dotnet/registry.yaml
index 2024718f4f..0b42cd2739 100644
--- a/model/dotnet/registry.yaml
+++ b/model/dotnet/registry.yaml
@@ -6,28 +6,28 @@ groups:
This document defines .NET related attributes.
attributes:
- id: dotnet.gc.heap.generation
- stability: experimental
+ stability: stable
type:
members:
- id: gen0
value: 'gen0'
brief: "Generation 0"
- stability: experimental
+ stability: stable
- id: gen1
value: 'gen1'
brief: "Generation 1"
- stability: experimental
+ stability: stable
- id: gen2
value: 'gen2'
brief: "Generation 2"
- stability: experimental
+ stability: stable
- id: loh
value: 'loh'
brief: "Large Object Heap"
- stability: experimental
+ stability: stable
- id: poh
value: 'poh'
brief: "Pinned Object Heap"
- stability: experimental
+ stability: stable
brief: Name of the garbage collector managed heap generation.
examples: ["gen0", "gen1", "gen2"]
diff --git a/model/dotnet/runtime-metrics.yaml b/model/dotnet/runtime-metrics.yaml
index 313ee3b574..eae15956ae 100644
--- a/model/dotnet/runtime-metrics.yaml
+++ b/model/dotnet/runtime-metrics.yaml
@@ -9,7 +9,7 @@ groups:
This metric reports the same values as accessing [`Environment.ProcessorCount`](https://learn.microsoft.com/dotnet/api/system.environment.processorcount).
instrument: updowncounter
unit: "{cpu}"
- stability: experimental
+ stability: stable
- id: metric.dotnet.process.cpu.time
type: metric
@@ -22,7 +22,7 @@ groups:
processor time properties on [`System.Diagnostics.Process`](https://learn.microsoft.com/dotnet/api/system.diagnostics.process).
instrument: counter
unit: "s"
- stability: experimental
+ stability: stable
attributes:
- ref: cpu.mode
requirement_level: required
@@ -37,7 +37,7 @@ groups:
This metric reports the same values as calling [`Environment.WorkingSet`](https://learn.microsoft.com/dotnet/api/system.environment.workingset).
instrument: updowncounter
unit: "By"
- stability: experimental
+ stability: stable
- id: metric.dotnet.gc.collections
type: metric
@@ -50,7 +50,7 @@ groups:
API to calculate exclusive collections per generation.
instrument: counter
unit: "{collection}"
- stability: experimental
+ stability: stable
attributes:
- ref: dotnet.gc.heap.generation
requirement_level: required
@@ -67,7 +67,7 @@ groups:
This metric reports the same values as calling [`GC.GetTotalAllocatedBytes()`](https://learn.microsoft.com/dotnet/api/system.gc.gettotalallocatedbytes).
instrument: counter
unit: "By"
- stability: experimental
+ stability: stable
- id: metric.dotnet.gc.last_collection.memory.committed_size
type: metric
@@ -86,7 +86,7 @@ groups:
future.
instrument: updowncounter
unit: "By"
- stability: experimental
+ stability: stable
- id: metric.dotnet.gc.last_collection.heap.size
type: metric
@@ -101,7 +101,7 @@ groups:
[`GC.GetGCMemoryInfo().GenerationInfo.SizeAfterBytes`](https://learn.microsoft.com/dotnet/api/system.gcgenerationinfo.sizeafterbytes).
instrument: updowncounter
unit: "By"
- stability: experimental
+ stability: stable
attributes:
- ref: dotnet.gc.heap.generation
requirement_level: required
@@ -118,7 +118,7 @@ groups:
[`GC.GetGCMemoryInfo().GenerationInfo.FragmentationAfterBytes`](https://learn.microsoft.com/dotnet/api/system.gcgenerationinfo.fragmentationafterbytes).
instrument: updowncounter
unit: "By"
- stability: experimental
+ stability: stable
attributes:
- ref: dotnet.gc.heap.generation
requirement_level: required
@@ -133,7 +133,7 @@ groups:
This metric reports the same values as calling [`GC.GetTotalPauseDuration()`](https://learn.microsoft.com/dotnet/api/system.gc.gettotalpauseduration).
instrument: counter
unit: "s"
- stability: experimental
+ stability: stable
- id: metric.dotnet.jit.compiled_il.size
type: metric
@@ -146,7 +146,7 @@ groups:
[`JitInfo.GetCompiledILBytes()`](https://learn.microsoft.com/dotnet/api/system.runtime.jitinfo.getcompiledilbytes).
instrument: counter
unit: "By"
- stability: experimental
+ stability: stable
- id: metric.dotnet.jit.compiled_methods
type: metric
@@ -161,7 +161,7 @@ groups:
[`JitInfo.GetCompiledMethodCount()`](https://learn.microsoft.com/dotnet/api/system.runtime.jitinfo.getcompiledmethodcount).
instrument: counter
unit: "{method}"
- stability: experimental
+ stability: stable
- id: metric.dotnet.jit.compilation.time
type: metric
@@ -176,7 +176,7 @@ groups:
[`JitInfo.GetCompilationTime()`](https://learn.microsoft.com/dotnet/api/system.runtime.jitinfo.getcompilationtime).
instrument: counter
unit: "s"
- stability: experimental
+ stability: stable
- id: metric.dotnet.monitor.lock_contentions
type: metric
@@ -191,7 +191,7 @@ groups:
[`Monitor.LockContentionCount`](https://learn.microsoft.com/dotnet/api/system.threading.monitor.lockcontentioncount).
instrument: counter
unit: "{contention}"
- stability: experimental
+ stability: stable
- id: metric.dotnet.thread_pool.thread.count
type: metric
@@ -203,7 +203,7 @@ groups:
This metric reports the same values as calling [`ThreadPool.ThreadCount`](https://learn.microsoft.com/dotnet/api/system.threading.threadpool.threadcount).
instrument: updowncounter
unit: "{thread}"
- stability: experimental
+ stability: stable
- id: metric.dotnet.thread_pool.work_item.count
type: metric
@@ -218,7 +218,7 @@ groups:
[`ThreadPool.CompletedWorkItemCount`](https://learn.microsoft.com/dotnet/api/system.threading.threadpool.completedworkitemcount).
instrument: counter
unit: "{work_item}"
- stability: experimental
+ stability: stable
- id: metric.dotnet.thread_pool.queue.length
type: metric
@@ -233,7 +233,7 @@ groups:
[`ThreadPool.PendingWorkItemCount`](https://learn.microsoft.com/dotnet/api/system.threading.threadpool.pendingworkitemcount).
instrument: updowncounter
unit: "{work_item}"
- stability: experimental
+ stability: stable
- id: metric.dotnet.timer.count
type: metric
@@ -245,7 +245,7 @@ groups:
This metric reports the same values as calling [`Timer.ActiveCount`](https://learn.microsoft.com/dotnet/api/system.threading.timer.activecount).
instrument: updowncounter
unit: "{timer}"
- stability: experimental
+ stability: stable
- id: metric.dotnet.assembly.count
type: metric
@@ -258,7 +258,7 @@ groups:
[`AppDomain.CurrentDomain.GetAssemblies().Length`](https://learn.microsoft.com/dotnet/api/system.appdomain.getassemblies).
instrument: updowncounter
unit: "{assembly}"
- stability: experimental
+ stability: stable
- id: metric.dotnet.exceptions
type: metric
@@ -271,7 +271,7 @@ groups:
[`AppDomain.CurrentDomain.FirstChanceException`](https://learn.microsoft.com/dotnet/api/system.appdomain.firstchanceexception).
instrument: counter
unit: "{exception}"
- stability: experimental
+ stability: stable
attributes:
- ref: error.type
note: ""
diff --git a/policies/group_stability.rego b/policies/group_stability.rego
index d3cb41718a..17d7f3dd91 100644
--- a/policies/group_stability.rego
+++ b/policies/group_stability.rego
@@ -12,6 +12,8 @@ deny[group_stability_violation(description, group.id, name)] {
"metric.kestrel.connection.duration", "metric.kestrel.tls_handshake.duration",
# TODO: https://github.com/open-telemetry/semantic-conventions/issues/1519
"resource.service",
+ # TODO: https://github.com/open-telemetry/semantic-conventions/issues/1616
+ "metric.dotnet.process.cpu.time",
}
not exceptions[group.id]