diff --git a/.chloggen/1006.yaml b/.chloggen/1006.yaml new file mode 100644 index 0000000000..a0216241ce --- /dev/null +++ b/.chloggen/1006.yaml @@ -0,0 +1,13 @@ +change_type: breaking + +component: messaging + +note: | + Support generic operations in messaging and rename metrics: + + - Make `messaging.operation.name` required and `messaging.operation.type` conditionally required when type is applicable. + - Rename `messaging.publish.messages` metric to `messaging.client.published.messages` + - Unify `messaging.publish.duration` and `messaging.receive.duration` metrics into `messaging.client.operation.duration` + - Unify `messaging.receive.messages` and `messaging.process.messages` metrics into `messaging.client.consumed.messages` + +issues: [1006, 947, 937] diff --git a/.chloggen/1087.yaml b/.chloggen/1087.yaml new file mode 100644 index 0000000000..d25ede66de --- /dev/null +++ b/.chloggen/1087.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: gen-ai +note: Use GenAI instead of LLM on GenAI trace semantic conventions and minor cleanups. +issues: [1087] diff --git a/.chloggen/1102.yaml b/.chloggen/1102.yaml new file mode 100755 index 0000000000..b80789491d --- /dev/null +++ b/.chloggen/1102.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 GenAI model server metrics for measuring LLM serving latency + +# 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: [1102] + +# (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/1120.yaml b/.chloggen/1120.yaml new file mode 100644 index 0000000000..c8129f3811 --- /dev/null +++ b/.chloggen/1120.yaml @@ -0,0 +1,12 @@ +change_type: breaking + +component: db + +note: | + Clean up `db.system` enum members: + + - remove `firstsql`, `mssqlcompact`, and `cloudscape` as the corresponding databases are discontinued. + - rename `cache` to `intersystems_cache` + - remove `coldfusion` as it is not a database. + +issues: [1110] diff --git a/.chloggen/1125.yaml b/.chloggen/1125.yaml new file mode 100644 index 0000000000..e5f68d29a6 --- /dev/null +++ b/.chloggen/1125.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: Rename `db.client.connections.*` attributes to `db.client.connection.*` + +# 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: [ 1125 ] + +# (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/1155.yaml b/.chloggen/1155.yaml new file mode 100644 index 0000000000..4b71d69ec3 --- /dev/null +++ b/.chloggen/1155.yaml @@ -0,0 +1,4 @@ +change_type: bug_fix +component: messaging +note: Update Kafka Spring example to align with the messaging spec +issues: [ 1155 ] diff --git a/.chloggen/1165.yaml b/.chloggen/1165.yaml new file mode 100644 index 0000000000..76e5ed376f --- /dev/null +++ b/.chloggen/1165.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: Clarify that `db.query.parameter.` is string representation of the parameter value + +# 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: [ 1165 ] + +# (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/1167.yaml b/.chloggen/1167.yaml new file mode 100644 index 0000000000..cc9655329e --- /dev/null +++ b/.chloggen/1167.yaml @@ -0,0 +1,4 @@ +change_type: bug_fix +component: http +note: "Relax requirement on when to set HTTP span status to Error from `MUST` to `SHOULD`." +issues: [1167, 1003] diff --git a/.chloggen/1168.yaml b/.chloggen/1168.yaml new file mode 100644 index 0000000000..1ba4683655 --- /dev/null +++ b/.chloggen/1168.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: messaging +note: Clarify how per-message attributes should be recorded for batch operations. +issues: [ 1168 ] diff --git a/.chloggen/1169.yaml b/.chloggen/1169.yaml new file mode 100644 index 0000000000..33c7de4a91 --- /dev/null +++ b/.chloggen/1169.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: messaging +note: Define sampling relevant attributes for messaging client spans +issues: [ 432, 1169 ] diff --git a/.chloggen/1200.yaml b/.chloggen/1200.yaml new file mode 100644 index 0000000000..9d40d16961 --- /dev/null +++ b/.chloggen/1200.yaml @@ -0,0 +1,6 @@ +change_type: enhancement +component: gen_ai +note: > + Rename `gen_ai.usage.prompt_tokens` to `gen_ai.usage.input_tokens` and `gen_ai.usage.completion_tokens` to `gen_ai.usage.output_tokens` + to align terminology between spans and metrics. +issues: [ 1200 ] diff --git a/.chloggen/1202.yaml b/.chloggen/1202.yaml new file mode 100644 index 0000000000..32e4265029 --- /dev/null +++ b/.chloggen/1202.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: gen_ai +note: Convert `gen_ai.operation.name` to enum and use it on spans +issues: [ 1202 ] diff --git a/.chloggen/815.yaml b/.chloggen/815.yaml new file mode 100644 index 0000000000..202d2713f9 --- /dev/null +++ b/.chloggen/815.yaml @@ -0,0 +1,8 @@ +change_type: breaking +component: messaging +note: > + Introduce common attributes for consumer group and subscription name instead of per-system ones: + - `messaging.consumer.group.name` instead of `messaging.kafka.consumer.group`, `messaging.rocketmq.client_group`, and `messaging.eventhubs.consumer.group`. + - `messaging.destination.subscription.name` instead of `messaging.servicebus.destination.subscription_name`. Use it in the Google Pub/Sub conventions. + +issues: [ 815 ] diff --git a/.chloggen/839.yaml b/.chloggen/839.yaml new file mode 100644 index 0000000000..1da8ca5ba8 --- /dev/null +++ b/.chloggen/839.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: gen-ai +note: Adding `gen_ai.request.top_k`, `gen_ai.request.presence_penalty`, `gen_ai.request.frequency_penalty` and `gen_ai.request.stop_sequences` attributes. +issues: [839] diff --git a/.chloggen/942.yaml b/.chloggen/942.yaml new file mode 100644 index 0000000000..d5920d949f --- /dev/null +++ b/.chloggen/942.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: messaging +note: Document `messaging.operation.name` for Azure messaging systems. +issues: [942] diff --git a/.chloggen/abbr.yaml b/.chloggen/abbr.yaml new file mode 100755 index 0000000000..31b3df5e42 --- /dev/null +++ b/.chloggen/abbr.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: all + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Define name abbreviations guidelines in attribute and metric names. + +# 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: [1121] + +# (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/align_es_spec.yaml b/.chloggen/align_es_spec.yaml new file mode 100755 index 0000000000..142eb7f6c9 --- /dev/null +++ b/.chloggen/align_es_spec.yaml @@ -0,0 +1,24 @@ +# 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: > + Align Elasticsearch span name to the general database span name guidelines. + Deprecates `db.elasticsearch.cluster.name` in favor of `db.namespace`. + +# 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: [1002] + +# (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/db_sanitization.yaml b/.chloggen/db_sanitization.yaml new file mode 100755 index 0000000000..a6d255ec26 --- /dev/null +++ b/.chloggen/db_sanitization.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: Specify sanitization for `db.query.text`. + +# 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: [717] + +# (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/gcp-client-libraries.yaml b/.chloggen/gcp-client-libraries.yaml new file mode 100755 index 0000000000..0ae23ba749 --- /dev/null +++ b/.chloggen/gcp-client-libraries.yaml @@ -0,0 +1,4 @@ +change_type: 'enhancement' +component: gcp +note: Introduces `gcp.client.service` scope attribute. +issues: [ 1047 ] diff --git a/.chloggen/merge_cpu_states.yaml b/.chloggen/merge_cpu_states.yaml new file mode 100755 index 0000000000..54ea54c032 --- /dev/null +++ b/.chloggen/merge_cpu_states.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: system + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Rename `process.cpu.state`, `container.cpu.state`, and `system.cpu.state` attributes into a common `cpu.mode` 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: [840] + +# (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/nodejs-metrics.yaml b/.chloggen/nodejs-metrics.yaml new file mode 100755 index 0000000000..51b11a961e --- /dev/null +++ b/.chloggen/nodejs-metrics.yaml @@ -0,0 +1,17 @@ +# 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: nodejs + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Introducing semantic conventions for Node.js runtime 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: [990] diff --git a/.chloggen/v8js-metrics.yaml b/.chloggen/v8js-metrics.yaml new file mode 100644 index 0000000000..276a49d500 --- /dev/null +++ b/.chloggen/v8js-metrics.yaml @@ -0,0 +1,17 @@ +# 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: v8js + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Introducing semantic conventions for V8 JS Engine runtime 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: [990] diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 132862aac6..f7360531b8 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -37,7 +37,7 @@ /model/registry/http.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers /model/registry/server.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers /model/registry/client.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers -/model/registry/network.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/model/registry/network.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers @open-telemetry/semconv-security-approvers /model/registry/error.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers /model/registry/url.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers /model/registry/user-agent.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers @@ -76,4 +76,14 @@ /model/trace/gen-ai.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-llm-approvers /docs/gen-ai/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-llm-approvers -# TODO - Add semconv area experts +# Security semantic conventions approvers +/model/registry/file.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers +/model/registry/dns.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers +/model/registry/process.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers +/model/registry/tls.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers +/model/registry/user.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers + +/model/metrics/dns.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers +/model/metrics/process-metrics.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers +/model/resource/process.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers +/model/network.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 33cf248bb7..92d1f8f1e3 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -28,6 +28,7 @@ body: - area:cloudevents - area:code - area:container + - area:cpu - area:db - area:deployment - area:destination @@ -71,6 +72,7 @@ body: - area:url - area:user-agent - area:user + - area:v8js - area:webengine # End semconv area list - type: textarea diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 4429b696e6..bb06caa150 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -21,6 +21,7 @@ body: - area:cloudevents - area:code - area:container + - area:cpu - area:db - area:deployment - area:destination @@ -64,6 +65,7 @@ body: - area:url - area:user-agent - area:user + - area:v8js - area:webengine # End semconv area list - type: textarea diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index 1a504ea5ce..01b2c53764 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -30,6 +30,7 @@ body: - area:cloudevents - area:code - area:container + - area:cpu - area:db - area:deployment - area:destination @@ -73,6 +74,7 @@ body: - area:url - area:user-agent - area:user + - area:v8js - area:webengine # End semconv area list - type: textarea diff --git a/.github/workflows/stale-pr.yml b/.github/workflows/stale-pr.yml index d5259a6140..c016b62e1c 100644 --- a/.github/workflows/stale-pr.yml +++ b/.github/workflows/stale-pr.yml @@ -12,7 +12,7 @@ jobs: repo-token: ${{ secrets.GITHUB_TOKEN }} stale-pr-message: 'This PR was marked stale due to lack of activity. It will be closed in 7 days.' close-pr-message: 'Closed as inactive. Feel free to reopen if this PR is still being worked on.' - exempt-pr-labels: 'bug,work in progress,experts needed' + exempt-pr-labels: 'bug,work in progress,experts needed,never stale' exempt-draft-pr: true # opt out of defaults to avoid marking issues as stale days-before-stale: -1 diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a4f606d30..dd3b88f886 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,7 +26,7 @@ - `device.app.lifecycle`: Reformat and update the `device.app.lifecycle` event description adds constraints for the possible values of the `android.state` and `ios.state`. (#794) Removes the `ios.lifecycle.events` and `android.lifecycle.events` attributes from the global registry and adds constraints for the possible values of the `android.state` and `ios.state` attributes. - + - `messaging`: Rename `messaging.client_id` to `messaging.client.id` (#935) - `rpc`: Rename`message.*` attributes under `rpc` to `rpc.message.*`. Deprecate old `message.*` attributes. (#854) @@ -51,7 +51,7 @@ The entirety of the registry now is generated using weaver with templates under the `templates/` directory. Snippets still require a hardcoded command. - + - `http`: List all HTTP client and server attributes in the corresponding table, remove common attributes from yaml and markdown. (#928) - `other`: Document patterns and suggestions for semconv code generation. (#551, #953) - `db`: Show applicable common attributes in individual database semantic conventions. (#973) @@ -72,14 +72,6 @@ - `net`: Add previously deprecated net attributes to registry (#1029) These attributes were deprecated in 1.13 -## Unreleased - -### Breaking - -### Features - -### Fixes - ## v1.25.0 ### 🛑 Breaking changes 🛑 diff --git a/Makefile b/Makefile index 1b6b4f499d..b2af508988 100644 --- a/Makefile +++ b/Makefile @@ -14,7 +14,7 @@ CHLOGGEN_CONFIG := .chloggen/config.yaml # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates # Keep links in model/README.md and .vscode/settings.json in sync! SEMCONVGEN_VERSION=0.24.0 -WEAVER_VERSION=0.2.0 +WEAVER_VERSION=0.5.0 # From where to resolve the containers (e.g. "otel/weaver"). CONTAINER_REPOSITORY=docker.io diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 2aa1b98447..fe0413bb19 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -40,6 +40,7 @@ Currently, the following namespaces exist: - [CloudEvents](cloudevents.md) - [Code](code.md) - [Container](container.md) +- [CPU](cpu.md) - [Db](db.md) - [Deployment](deployment.md) - [Destination](destination.md) @@ -85,6 +86,7 @@ Currently, the following namespaces exist: - [URL](url.md) - [User](user.md) - [User Agent](user-agent.md) +- [V8js](v8js.md) - [Webengine](webengine.md) [developers recommendations]: ../general/attribute-naming.md#recommendations-for-application-developers diff --git a/docs/attributes-registry/container.md b/docs/attributes-registry/container.md index 12ae8414bf..fdca43d789 100644 --- a/docs/attributes-registry/container.md +++ b/docs/attributes-registry/container.md @@ -18,7 +18,6 @@ A container instance. | `container.command` | string | The command used to run the container (i.e. the command name). [1] | `otelcontribcol` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `container.command_args` | string[] | All the command arguments (including the command/executable itself) run by the container. [2] | `["otelcontribcol, --config, config.yaml"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `container.command_line` | string | The full command run by the container as a single string representing the full command. [2] | `otelcontribcol --config config.yaml` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `container.cpu.state` | string | The CPU state for this data point. | `user`; `kernel` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `container.id` | string | Container ID. Usually a UUID, as for example used to [identify Docker containers](https://docs.docker.com/engine/reference/run/#container-identification). The UUID might be abbreviated. | `a3bf90e006b2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `container.image.id` | string | Runtime specific image identifier. Usually a hash algorithm followed by a UUID. [2] | `sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `container.image.name` | string | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -36,18 +35,19 @@ The ID is assigned by the container runtime and can vary in different environmen **[3]:** [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. -`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 | -| -------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `kernel` | When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `system` | When CPU is used by the system (host OS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `user` | When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - ## Container Deprecated Attributes Describes deprecated container attributes. | Attribute | Type | Description | Examples | Stability | | ------------------------ | ------ | ------------------------------------------ | --------------------------- | --------------------------------------------------------------------------------------------- | +| `container.cpu.state` | string | Deprecated, use `cpu.mode` instead. | `user`; `kernel` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `cpu.mode` | | `container.labels.` | string | Deprecated, use `container.label` instead. | `container.label.app=nginx` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
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 | +| -------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `kernel` | When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system` | When CPU is used by the system (host OS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `user` | When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/cpu.md b/docs/attributes-registry/cpu.md new file mode 100644 index 0000000000..2e405a8a83 --- /dev/null +++ b/docs/attributes-registry/cpu.md @@ -0,0 +1,28 @@ + + + + + +# CPU + +## CPU Attributes + +Attributes specific to a cpu instance. + +| Attribute | Type | Description | Examples | Stability | +| ---------- | ------ | ------------------- | ---------------- | ---------------------------------------------------------------- | +| `cpu.mode` | string | The mode of the CPU | `user`; `system` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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 | +| ----------- | ----------- | ---------------------------------------------------------------- | +| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `kernel` | kernel | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 3af5405da2..db78b93f6b 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -17,17 +17,17 @@ This group defines the attributes used to describe telemetry in the context of databases. -| Attribute | Type | Description | Examples | Stability | -| --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `db.client.connections.pool.name` | 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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.client.connections.state` | string | The state of a connection in the pool | `idle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.collection.name` | string | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.namespace` | string | The name of the database, fully qualified within the server address and port. [2] | `customers`; `test.users` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.operation.batch.size` | int | The number of queries included in a [batch operation](/docs/database/database-spans.md#batch-operations). [3] | `2`; `3`; `4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.operation.name` | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.query.parameter.` | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [5] | `someval`; `55` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.query.text` | string | The database query being executed. [6] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.system` | string | The database management system (DBMS) product as identified by the client instrumentation. [7] | `other_sql`; `adabas`; `cache` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| -------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `db.client.connection.pool.name` | 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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.connection.state` | string | The state of a connection in the pool | `idle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.collection.name` | string | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.namespace` | string | The name of the database, fully qualified within the server address and port. [2] | `customers`; `test.users` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.operation.batch.size` | int | The number of queries included in a [batch operation](/docs/database/database-spans.md#batch-operations). [3] | `2`; `3`; `4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.operation.name` | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.query.parameter.` | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [5] | `someval`; `55` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.query.text` | string | The database query being executed. [6] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.system` | string | The database management system (DBMS) product as identified by the client instrumentation. [7] | `other_sql`; `adabas`; `cache` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. @@ -46,11 +46,13 @@ For batch operations, if the individual operations are known to have the same op **[5]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. -**[6]:** 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. +**[6]:** 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. **[7]:** 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. -`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. +`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 | | ------ | ----------- | ---------------------------------------------------------------- | @@ -59,61 +61,62 @@ If a parameter has no name and instead is referenced only by index, then `` `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 | -| --------------- | -------------------------------------------------- | ---------------------------------------------------------------- | -| `adabas` | Adabas (Adaptable Database System) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cassandra` | Apache Cassandra | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `clickhouse` | ClickHouse | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cloudscape` | Cloudscape | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cockroachdb` | CockroachDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `coldfusion` | ColdFusion IMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cosmosdb` | Microsoft Azure Cosmos DB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `couchbase` | Couchbase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `couchdb` | CouchDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db2` | IBM Db2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `derby` | Apache Derby | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `dynamodb` | Amazon DynamoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `edb` | EnterpriseDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `elasticsearch` | Elasticsearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `filemaker` | FileMaker | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `firebird` | Firebird | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `firstsql` | FirstSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `geode` | Apache Geode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `h2` | H2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `hanadb` | SAP HANA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `hbase` | Apache HBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `hive` | Apache Hive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `hsqldb` | HyperSQL DataBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `influxdb` | InfluxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `informix` | Informix | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `ingres` | Ingres | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `instantdb` | InstantDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `interbase` | InterBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mariadb` | MariaDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `maxdb` | SAP MaxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mssql` | Microsoft SQL Server | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mssqlcompact` | Microsoft SQL Server Compact | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mysql` | MySQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `netezza` | Netezza | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `opensearch` | OpenSearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `oracle` | Oracle Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `other_sql` | Some other SQL database. Fallback only. See notes. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `pervasive` | Pervasive PSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `pointbase` | PointBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `postgresql` | PostgreSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `progress` | Progress Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `redis` | Redis | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `redshift` | Amazon Redshift | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `spanner` | Cloud Spanner | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `sqlite` | SQLite | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `sybase` | Sybase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `teradata` | Teradata | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `trino` | Trino | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `vertica` | Vertica | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Value | Description | Stability | +| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| `adabas` | Adabas (Adaptable Database System) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cache` | Deprecated, use `intersystems_cache` instead. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `intersystems_cache`. | +| `cassandra` | Apache Cassandra | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `clickhouse` | ClickHouse | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cloudscape` | Deprecated, use `other_sql` instead. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `other_sql`. | +| `cockroachdb` | CockroachDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `coldfusion` | Deprecated, no replacement at this time. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | +| `cosmosdb` | Microsoft Azure Cosmos DB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `couchbase` | Couchbase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `couchdb` | CouchDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db2` | IBM Db2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `derby` | Apache Derby | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dynamodb` | Amazon DynamoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `edb` | EnterpriseDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `elasticsearch` | Elasticsearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `filemaker` | FileMaker | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `firebird` | Firebird | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `firstsql` | Deprecated, use `other_sql` instead. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `other_sql`. | +| `geode` | Apache Geode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `h2` | H2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hanadb` | SAP HANA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hbase` | Apache HBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hive` | Apache Hive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hsqldb` | HyperSQL DataBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `influxdb` | InfluxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `informix` | Informix | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ingres` | Ingres | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `instantdb` | InstantDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interbase` | InterBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `intersystems_cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mariadb` | MariaDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `maxdb` | SAP MaxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mssql` | Microsoft SQL Server | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mssqlcompact` | Deprecated, Microsoft SQL Server Compact is discontinued. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed, use `other_sql` instead. | +| `mysql` | MySQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `netezza` | Netezza | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `opensearch` | OpenSearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `oracle` | Oracle Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other_sql` | Some other SQL database. Fallback only. See notes. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pervasive` | Pervasive PSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pointbase` | PointBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `postgresql` | PostgreSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `progress` | Progress Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `redis` | Redis | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `redshift` | Amazon Redshift | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `spanner` | Cloud Spanner | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `sqlite` | SQLite | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `sybase` | Sybase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `teradata` | Teradata | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `trino` | Trino | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vertica` | Vertica | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## Db Cassandra Attributes @@ -189,21 +192,22 @@ This group defines attributes for Azure Cosmos DB. "Describes deprecated db attributes." -| Attribute | Type | Description | Examples | Stability | -| -------------------------- | ------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `db.cassandra.table` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | -| `db.connection_string` | string | Deprecated, use `server.address`, `server.port` attributes instead. | `Server=(localdb)\v11.0;Integrated Security=true;` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
"Replaced by `server.address` and `server.port`." | -| `db.cosmosdb.container` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | -| `db.instance.id` | string | Deprecated, no general replacement at this time. For Elasticsearch, use `db.elasticsearch.node.name` instead. | `mysql-e26b99z.example.com` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, no general replacement at this time. For Elasticsearch, use `db.elasticsearch.node.name` instead. | -| `db.jdbc.driver_classname` | string | Removed, no replacement at this time. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed as not used. | -| `db.mongodb.collection` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | -| `db.mssql.instance_name` | string | Deprecated, SQL Server instance is now populated as a part of `db.namespace` attribute. | `MSSQLSERVER` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, no replacement at this time. | -| `db.name` | string | Deprecated, use `db.namespace` instead. | `customers`; `main` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | -| `db.operation` | string | Deprecated, use `db.operation.name` instead. | `findAndModify`; `HMSET`; `SELECT` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.operation.name`. | -| `db.redis.database_index` | int | Deprecated, use `db.namespace` instead. | `0`; `1`; `15` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | -| `db.sql.table` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | -| `db.statement` | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.query.text`. | -| `db.user` | string | Deprecated, no replacement at this time. | `readonly_user`; `reporting_user` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
No replacement at this time. | +| Attribute | Type | Description | Examples | Stability | +| ------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `db.cassandra.table` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | +| `db.connection_string` | string | Deprecated, use `server.address`, `server.port` attributes instead. | `Server=(localdb)\v11.0;Integrated Security=true;` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
"Replaced by `server.address` and `server.port`." | +| `db.cosmosdb.container` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | +| `db.elasticsearch.cluster.name` | string | Deprecated, use `db.namespace` instead. | `e9106fc68e3044f0b1475b04bf4ffd5f` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | +| `db.instance.id` | string | Deprecated, no general replacement at this time. For Elasticsearch, use `db.elasticsearch.node.name` instead. | `mysql-e26b99z.example.com` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, no general replacement at this time. For Elasticsearch, use `db.elasticsearch.node.name` instead. | +| `db.jdbc.driver_classname` | string | Removed, no replacement at this time. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed as not used. | +| `db.mongodb.collection` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | +| `db.mssql.instance_name` | string | Deprecated, SQL Server instance is now populated as a part of `db.namespace` attribute. | `MSSQLSERVER` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, no replacement at this time. | +| `db.name` | string | Deprecated, use `db.namespace` instead. | `customers`; `main` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | +| `db.operation` | string | Deprecated, use `db.operation.name` instead. | `findAndModify`; `HMSET`; `SELECT` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.operation.name`. | +| `db.redis.database_index` | int | Deprecated, use `db.namespace` instead. | `0`; `1`; `15` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | +| `db.sql.table` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | +| `db.statement` | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.query.text`. | +| `db.user` | string | Deprecated, no replacement at this time. | `readonly_user`; `reporting_user` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
No replacement at this time. | ## Db Elasticsearch Attributes @@ -211,7 +215,6 @@ This group defines attributes for Elasticsearch. | Attribute | Type | Description | Examples | Stability | | ----------------------------------- | ------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `db.elasticsearch.cluster.name` | string | Represents the identifier of an Elasticsearch cluster. | `e9106fc68e3044f0b1475b04bf4ffd5f` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [8] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -221,10 +224,19 @@ This group defines attributes for Elasticsearch. "Describes deprecated db metrics attributes." -| Attribute | Type | Description | Examples | Stability | -| ----------- | ------ | ---------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------- | -| `pool.name` | string | Deprecated, use `db.client.connections.pool.name` instead. | `myDataSource` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.client.connections.pool.name`. | -| `state` | string | Deprecated, use `db.client.connections.state` instead. | `idle` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.client.connections.state`. | +| Attribute | Type | Description | Examples | Stability | +| --------------------------------- | ------ | --------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------ | +| `db.client.connections.pool.name` | string | Deprecated, use `db.client.connection.pool.name` instead. | `myDataSource` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.client.connection.pool.name`. | +| `db.client.connections.state` | string | Deprecated, use `db.client.connection.state` instead. | `idle` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.client.connection.state`. | +| `pool.name` | string | Deprecated, use `db.client.connection.pool.name` instead. | `myDataSource` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.client.connection.pool.name`. | +| `state` | string | Deprecated, use `db.client.connection.state` instead. | `idle` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
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 | +| ------ | ----------- | ---------------------------------------------------------------- | +| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `used` | used | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `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/gcp.md b/docs/attributes-registry/gcp.md index 0a8ba6319c..cade703150 100644 --- a/docs/attributes-registry/gcp.md +++ b/docs/attributes-registry/gcp.md @@ -6,9 +6,28 @@ # GCP +- [Gcp](#gcp-attributes) +- [Gcp Client](#gcp-client-attributes) - [Gcp Cloud Run](#gcp-cloud-run-attributes) - [Gcp Gce](#gcp-gce-attributes) +## GCP Attributes + +Attributes for Google Cloud + +| Attribute | Type | Description | Examples | Stability | +| --------- | ---- | ----------- | -------- | --------- | + +## GCP Client Attributes + +Attributes for Google Cloud client libraries. + +| Attribute | Type | Description | Examples | Stability | +| -------------------- | ------ | ------------------------------------------------------------------------------------------ | ----------------------------------------------------- | ---------------------------------------------------------------- | +| `gcp.client.service` | string | Identifies the Google Cloud service for which the official client library is intended. [1] | `appengine`; `run`; `firestore`; `alloydb`; `spanner` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[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'. + ## GCP Cloud Run Attributes This document defines attributes for Google Cloud Run. diff --git a/docs/attributes-registry/gen-ai.md b/docs/attributes-registry/gen-ai.md index 09b8b913f9..a9c090a32b 100644 --- a/docs/attributes-registry/gen-ai.md +++ b/docs/attributes-registry/gen-ai.md @@ -6,32 +6,56 @@ # Gen AI +- [Gen Ai](#gen-ai-attributes) +- [Gen Ai Deprecated](#gen-ai-deprecated-attributes) + ## Gen AI Attributes -This document defines the attributes used to describe telemetry in the context of LLM (Large Language Models) requests and responses. - -| Attribute | Type | Description | Examples | Stability | -| -------------------------------- | -------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `gen_ai.completion` | string | The full response received from the LLM. [1] | `[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.operation.name` | string | The name of the operation being performed. | `chat`; `completion` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.prompt` | string | The full prompt sent to an LLM. [2] | `[{'role': 'user', 'content': 'What is the capital of France?'}]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.request.max_tokens` | int | The maximum number of tokens the LLM generates for a request. | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.request.model` | string | The name of the LLM a request is being made to. | `gpt-4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.request.temperature` | double | The temperature setting for the LLM request. | `0.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.request.top_p` | double | The top_p sampling setting for the LLM request. | `1.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.response.finish_reasons` | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.response.id` | string | The unique identifier for the completion. | `chatcmpl-123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.response.model` | string | The name of the LLM a response was generated from. | `gpt-4-0613` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.system` | string | The Generative AI product as identified by the client instrumentation. [3] | `openai` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.token.type` | string | The type of token being counted. | `input`; `output` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.usage.completion_tokens` | int | The number of tokens used in the LLM response (completion). | `180` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.usage.prompt_tokens` | int | The number of tokens used in the LLM prompt. | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +This document defines the attributes used to describe telemetry in the context of Generative Artificial Intelligence (GenAI) Models requests and responses. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `gen_ai.completion` | string | The full response received from the GenAI model. [1] | `[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.operation.name` | string | The name of the operation being performed. [2] | `chat`; `text_completion` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.prompt` | string | The full prompt sent to the GenAI model. [3] | `[{'role': 'user', 'content': 'What is the capital of France?'}]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.request.frequency_penalty` | double | The frequency penalty setting for the GenAI request. | `0.1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.request.max_tokens` | int | The maximum number of tokens the model generates for a request. | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.request.model` | string | The name of the GenAI model a request is being made to. | `gpt-4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.request.presence_penalty` | double | The presence penalty setting for the GenAI request. | `0.1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.request.stop_sequences` | string[] | List of sequences that the model will use to stop generating further tokens. | `["forest", "lived"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.request.temperature` | double | The temperature setting for the GenAI request. | `0.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.request.top_k` | double | The top_k sampling setting for the GenAI request. | `1.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.request.top_p` | double | The top_p sampling setting for the GenAI request. | `1.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.response.finish_reasons` | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.response.id` | string | The unique identifier for the completion. | `chatcmpl-123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.response.model` | string | The name of the model that generated the response. | `gpt-4-0613` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.system` | string | The Generative AI product as identified by the client or server instrumentation. [4] | `openai` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.token.type` | string | The type of token being counted. | `input`; `output` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.usage.input_tokens` | int | The number of tokens used in the GenAI input (prompt). | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.usage.output_tokens` | int | The number of tokens used in the GenAI response (completion). | `180` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) -**[2]:** It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) +**[2]:** 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. + +**[3]:** It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + +**[4]:** 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. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. -**[3]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` 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 | +| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `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. @@ -48,3 +72,12 @@ This document defines the attributes used to describe telemetry in the context o | -------- | ------------------------------------------ | ---------------------------------------------------------------- | | `input` | Input tokens (prompt, input, etc.) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `output` | Output tokens (completion, response, etc.) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Gen AI Deprecated Attributes + +Describes deprecated `gen_ai` attributes. + +| Attribute | Type | Description | Examples | Stability | +| -------------------------------- | ---- | ----------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | +| `gen_ai.usage.completion_tokens` | int | Deprecated, use `gen_ai.usage.output_tokens` instead. | `42` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `gen_ai.usage.output_tokens` attribute. | +| `gen_ai.usage.prompt_tokens` | int | Deprecated, use `gen_ai.usage.input_tokens` instead. | `42` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `gen_ai.usage.input_tokens` attribute. | diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index 1a80f6d13d..dd69d0c13e 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -23,50 +23,57 @@ Attributes describing telemetry around messaging systems and messaging activitie | ----------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | ---------------------------------------------------------------- | | `messaging.batch.message_count` | int | The number of messages sent, received, or processed in the scope of the batching operation. [1] | `0`; `1`; `2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.client.id` | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.consumer.group.name` | string | The name of the consumer group with which a consumer is associated. [2] | `my-group`; `indexer` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.destination.anonymous` | boolean | A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name). | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.destination.name` | string | The message destination name [2] | `MyQueue`; `MyTopic` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.destination.name` | string | The message destination name [3] | `MyQueue`; `MyTopic` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.destination.partition.id` | string | The identifier of the partition messages are sent to or received from, unique within the `messaging.destination.name`. | `1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [3] | `/customers/{customerId}` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.destination.subscription.name` | string | The name of the destination subscription from which a message is consumed. [4] | `subscription-a` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [5] | `/customers/{customerId}` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.destination.temporary` | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.destination_publish.anonymous` | boolean | A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name). | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.destination_publish.name` | string | The name of the original destination the message was published to [4] | `MyQueue`; `MyTopic` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.message.body.size` | int | The size of the message body in bytes. [5] | `1439` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.destination_publish.name` | string | The name of the original destination the message was published to [6] | `MyQueue`; `MyTopic` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.message.body.size` | int | The size of the message body in bytes. [7] | `1439` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.message.conversation_id` | string | The conversation ID identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [6] | `2738` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [8] | `2738` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.operation.name` | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.operation.type` | string | A string identifying the type of the messaging operation. [7] | `publish`; `create`; `receive` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.system` | string | The messaging system as identified by the client instrumentation. [8] | `activemq`; `aws_sqs`; `eventgrid` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.operation.type` | string | A string identifying the type of the messaging operation. [9] | `publish`; `create`; `receive` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.system` | string | The messaging system as identified by the client instrumentation. [10] | `activemq`; `aws_sqs`; `eventgrid` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[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. -**[2]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If +**[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. + +**[3]:** 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]:** 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. +**[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. + +**[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. -**[4]:** The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If +**[6]:** The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If the broker doesn't have such notion, the original destination name SHOULD uniquely identify the broker. -**[5]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed +**[7]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed body size should be used. -**[6]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed +**[8]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed size should be used. -**[7]:** If a custom value is used, it MUST be of low cardinality. +**[9]:** If a custom value is used, it MUST be of low cardinality. -**[8]:** 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. +**[10]:** 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 | -| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `process` | One or more messages are delivered to or processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `settle` | One or more messages are settled. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Value | Description | Stability | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | +| `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `deliver` | Deprecated. Use `process` instead. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `process`. | +| `process` | One or more messages are processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `settle` | One or more messages are settled. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `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. @@ -88,20 +95,23 @@ size should be used. Describes deprecated messaging attributes. -| Attribute | Type | Description | Examples | Stability | -| --------------------------------------- | ------ | ------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| `messaging.client_id` | string | Deprecated, use `messaging.client.id` instead. | `client-5`; `myhost@8742@s8083jm` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.client.id`. | -| `messaging.kafka.destination.partition` | int | Deprecated, use `messaging.destination.partition.id` instead. | `2` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.destination.partition.id`. | -| `messaging.operation` | string | Deprecated, use `messaging.operation.type` instead. | `publish`; `create`; `process` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.operation.type`. | +| Attribute | Type | Description | Examples | Stability | +| ---------------------------------------------------- | ------ | ----------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `messaging.client_id` | string | Deprecated, use `messaging.client.id` instead. | `client-5`; `myhost@8742@s8083jm` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.client.id`. | +| `messaging.eventhubs.consumer.group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `$Default` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name`. | +| `messaging.kafka.consumer.group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `my-group` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name`. | +| `messaging.kafka.destination.partition` | int | Deprecated, use `messaging.destination.partition.id` instead. | `2` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.destination.partition.id`. | +| `messaging.operation` | string | Deprecated, use `messaging.operation.type` instead. | `publish`; `create`; `process` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.operation.type`. | +| `messaging.rocketmq.client_group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `myConsumerGroup` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name` on the consumer spans. No replacement for producer spans. | +| `messaging.servicebus.destination.subscription_name` | string | Deprecated, use `messaging.servicebus.destination.subscription_name` instead. | `subscription-a` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.servicebus.destination.subscription_name`. | ## Messaging Eventhubs Attributes This group describes attributes specific to Azure Event Hubs. -| Attribute | Type | Description | Examples | Stability | -| ------------------------------------------- | ------ | -------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------- | -| `messaging.eventhubs.consumer.group` | string | The name of the consumer group the event consumer is associated with. | `indexer` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.eventhubs.message.enqueued_time` | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| ------------------------------------------- | ---- | -------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------- | +| `messaging.eventhubs.message.enqueued_time` | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## Messaging GCP Pubsub Attributes @@ -118,14 +128,13 @@ This group describes attributes specific to GCP Pub/Sub. This group describes attributes specific to Apache Kafka. -| Attribute | Type | Description | Examples | Stability | -| ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ---------------------------------------------------------------- | -| `messaging.kafka.consumer.group` | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.kafka.message.key` | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [9] | `myKey` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.kafka.message.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.kafka.message.tombstone` | boolean | A boolean that is true if the message is a tombstone. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------- | +| `messaging.kafka.message.key` | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [11] | `myKey` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.kafka.message.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.kafka.message.tombstone` | boolean | A boolean that is true if the message is a tombstone. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[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. +**[11]:** 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. ## Messaging RabbitMQ Attributes @@ -142,7 +151,6 @@ This group describes attributes specific to RocketMQ. | Attribute | Type | Description | Examples | Stability | | ----------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | ---------------------------------------------------------------- | -| `messaging.rocketmq.client_group` | string | Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. | `myConsumerGroup` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.rocketmq.consumption_model` | string | Model of message consumption. This only applies to consumer spans. | `clustering`; `broadcasting` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.rocketmq.message.delay_time_level` | int | The delay time level for delay message, which determines the message delay time. | `3` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.rocketmq.message.delivery_timestamp` | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -172,12 +180,11 @@ This group describes attributes specific to RocketMQ. This group describes attributes specific to Azure Service Bus. -| Attribute | Type | Description | Examples | Stability | -| ---------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------- | -| `messaging.servicebus.destination.subscription_name` | string | The name of the subscription in the topic messages are received from. | `mySubscription` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.servicebus.disposition_status` | string | Describes the [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). | `complete`; `abandon`; `dead_letter` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.servicebus.message.delivery_count` | int | Number of deliveries that have been attempted for this message. | `2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.servicebus.message.enqueued_time` | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| --------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------- | +| `messaging.servicebus.disposition_status` | string | Describes the [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). | `complete`; `abandon`; `dead_letter` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.servicebus.message.delivery_count` | int | Number of deliveries that have been attempted for this message. | `2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.servicebus.message.enqueued_time` | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `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. diff --git a/docs/attributes-registry/process.md b/docs/attributes-registry/process.md index 2e525794c2..9b47e08949 100644 --- a/docs/attributes-registry/process.md +++ b/docs/attributes-registry/process.md @@ -7,7 +7,7 @@ # Process - [Process](#process-attributes) -- [Process Cpu](#process-cpu-attributes) +- [Process Deprecated](#process-deprecated-attributes) ## Process Attributes @@ -33,7 +33,7 @@ An operating system process. | `process.real_user.id` | int | The real user ID (RUID) of the process. | `1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `process.real_user.name` | string | The username of the real user of the process. | `operator` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `process.runtime.description` | string | An additional description about the runtime of the process, for example a specific vendor customization of the runtime environment. | `Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `process.runtime.name` | string | The name of the runtime of this process. For compiled native binaries, this SHOULD be the name of the compiler. | `OpenJDK Runtime Environment` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.runtime.name` | string | The name of the runtime of this process. | `OpenJDK Runtime Environment` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `process.runtime.version` | string | The version of the runtime of this process, as returned by the runtime without modification. | `14.0.2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `process.saved_user.id` | int | The saved user ID (SUID) of the process. | `1002` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `process.saved_user.name` | string | The username of the saved user. | `operator` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -58,13 +58,13 @@ An operating system process. | `major` | major | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `minor` | minor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Process Cpu Attributes +## Process Deprecated Attributes -Attributes for process CPU +Deprecated process attributes. -| Attribute | Type | Description | Examples | Stability | -| ------------------- | ------ | ----------------------------- | ------------------------ | ---------------------------------------------------------------- | -| `process.cpu.state` | string | The CPU state of the process. | `system`; `user`; `wait` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| ------------------- | ------ | ----------------------------------- | ------------------------ | ------------------------------------------------------------------------------------- | +| `process.cpu.state` | string | Deprecated, use `cpu.mode` instead. | `system`; `user`; `wait` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `cpu.mode` | `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. diff --git a/docs/attributes-registry/system.md b/docs/attributes-registry/system.md index de49928773..c504f989f9 100644 --- a/docs/attributes-registry/system.md +++ b/docs/attributes-registry/system.md @@ -23,14 +23,22 @@ Describes System attributes | --------------- | ------ | --------------------- | -------------- | ---------------------------------------------------------------- | | `system.device` | string | The device identifier | `(identifier)` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## System Cpu Attributes +## System CPU Attributes Describes System CPU attributes -| Attribute | Type | Description | Examples | Stability | -| --------------------------- | ------ | ------------------------------- | ------------------- | ---------------------------------------------------------------- | -| `system.cpu.logical_number` | int | The logical CPU number [0..n-1] | `1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `system.cpu.state` | string | The state of the CPU | `idle`; `interrupt` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| --------------------------- | ---- | ------------------------------- | -------- | ---------------------------------------------------------------- | +| `system.cpu.logical_number` | int | The logical CPU number [0..n-1] | `1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## System Deprecated Attributes + +Deprecated system attributes. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------- | ------ | ------------------------------------------------ | ------------------- | --------------------------------------------------------------------------------------------------- | +| `system.cpu.state` | string | Deprecated, use `cpu.mode` instead. | `idle`; `interrupt` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `cpu.mode` | +| `system.processes.status` | string | Deprecated, use `system.process.status` instead. | `running` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
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. @@ -44,14 +52,6 @@ Describes System CPU attributes | `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## System Deprecated Attributes - -Deprecated system attributes. - -| Attribute | Type | Description | Examples | Stability | -| ------------------------- | ------ | ------------------------------------------------ | --------- | --------------------------------------------------------------------------------------------------- | -| `system.processes.status` | string | Deprecated, use `system.process.status` instead. | `running` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `system.process.status`. | - `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/v8js.md b/docs/attributes-registry/v8js.md new file mode 100644 index 0000000000..2e2bf3fec3 --- /dev/null +++ b/docs/attributes-registry/v8js.md @@ -0,0 +1,37 @@ + + + + + +# V8js + +## V8js Attributes + +Describes V8 JS Engine Runtime related attributes. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------- | ------ | ---------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------- | +| `v8js.gc.type` | string | The type of garbage collection. | `major`; `minor`; `incremental` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `v8js.heap.space.name` | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** 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 | +| ------------- | ---------------------------------------- | ---------------------------------------------------------------- | +| `incremental` | Incremental (Incremental Marking). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `major` | Major (Mark Sweep Compact). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `minor` | Minor (Scavenge). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `weakcb` | Weak Callbacks (Process Weak Callbacks). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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 | +| -------------------- | -------------------------- | ---------------------------------------------------------------- | +| `code_space` | Code memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index abfb3d4f1f..fec15f7cf0 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -38,7 +38,7 @@ described on this page. | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [11] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [13] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [13] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. @@ -60,9 +60,11 @@ For batch operations, if the individual operations are known to have the same op **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[9]:** 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. +**[9]:** 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. -**[10]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. +**[10]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). **[11]:** 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 f4313b0bcd..6fa48db887 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -41,7 +41,7 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [7] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [10] | `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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [11] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [11] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. @@ -59,9 +59,11 @@ For batch operations, if the individual operations are known to have the same op **[6]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[7]:** 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. +**[7]:** 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. -**[8]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. +**[8]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). **[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. diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 8f2eb662a5..332a0f9dda 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -146,12 +146,9 @@ If a database operation involved multiple network calls (for example retries), t | Value | Description | Stability | |---|---|---| | `adabas` | Adabas (Adaptable Database System) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cassandra` | Apache Cassandra | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `clickhouse` | ClickHouse | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cloudscape` | Cloudscape | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cockroachdb` | CockroachDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `coldfusion` | ColdFusion IMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cosmosdb` | Microsoft Azure Cosmos DB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `couchbase` | Couchbase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `couchdb` | CouchDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -162,7 +159,6 @@ If a database operation involved multiple network calls (for example retries), t | `elasticsearch` | Elasticsearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `filemaker` | FileMaker | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `firebird` | Firebird | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `firstsql` | FirstSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `geode` | Apache Geode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `h2` | H2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `hanadb` | SAP HANA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -174,12 +170,12 @@ If a database operation involved multiple network calls (for example retries), t | `ingres` | Ingres | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `instantdb` | InstantDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `interbase` | InterBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `intersystems_cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mariadb` | MariaDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `maxdb` | SAP MaxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mssql` | Microsoft SQL Server | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mssqlcompact` | Microsoft SQL Server Compact | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mysql` | MySQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `netezza` | Netezza | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -247,10 +243,10 @@ This metric is [required][MetricRequired]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.client.connections.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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.client.connections.state`](/docs/attributes-registry/db.md) | string | The state of a connection in the pool | `idle` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.client.connection.state`](/docs/attributes-registry/db.md) | string | The state of a connection in the pool | `idle` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`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. +`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 | |---|---|---| @@ -293,7 +289,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.client.connections.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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -331,7 +327,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.client.connections.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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -369,7 +365,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.client.connections.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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -407,7 +403,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.client.connections.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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -445,7 +441,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.client.connections.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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -483,7 +479,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.client.connections.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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -521,7 +517,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.client.connections.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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -559,7 +555,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.client.connections.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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 766c3d0237..88093233d8 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -13,6 +13,7 @@ linkTitle: Client Calls - [Name](#name) - [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) - [Semantic Conventions for specific database technologies](#semantic-conventions-for-specific-database-technologies) @@ -99,7 +100,7 @@ These attributes will usually be the same for all operations performed over the | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [12] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this database system. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [13] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [14] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [14] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[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. @@ -125,9 +126,11 @@ For batch operations, if the individual operations are known to have the same op **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[10]:** 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. +**[10]:** 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. -**[11]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. +**[11]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). **[12]:** 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. @@ -144,12 +147,9 @@ If a parameter has no name and instead is referenced only by index, then `` | Value | Description | Stability | |---|---|---| | `adabas` | Adabas (Adaptable Database System) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cassandra` | Apache Cassandra | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `clickhouse` | ClickHouse | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cloudscape` | Cloudscape | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cockroachdb` | CockroachDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `coldfusion` | ColdFusion IMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cosmosdb` | Microsoft Azure Cosmos DB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `couchbase` | Couchbase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `couchdb` | CouchDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -160,7 +160,6 @@ If a parameter has no name and instead is referenced only by index, then `` | `elasticsearch` | Elasticsearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `filemaker` | FileMaker | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `firebird` | Firebird | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `firstsql` | FirstSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `geode` | Apache Geode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `h2` | H2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `hanadb` | SAP HANA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -172,12 +171,12 @@ If a parameter has no name and instead is referenced only by index, then `` | `ingres` | Ingres | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `instantdb` | InstantDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `interbase` | InterBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `intersystems_cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mariadb` | MariaDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `maxdb` | SAP MaxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mssql` | Microsoft SQL Server | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mssqlcompact` | Microsoft SQL Server Compact | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mysql` | MySQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `netezza` | Netezza | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -229,6 +228,17 @@ Back ends could, for example, use the provided identifier to determine the appro When additional attributes are added that only apply to a specific DBMS, its identifier SHOULD be used as a namespace in the attribute key as for the attributes in the sections below. +## Sanitization of `db.query.text` + +The `db.query.text` SHOULD be collected by default only if there is sanitization that excludes sensitive information. +Sanitization SHOULD replace all literals with a placeholder value. +Such literals include, but are not limited to, String, Numeric, Date and Time, +Boolean, Interval, Binary, and Hexadecimal literals. +The placeholder value SHOULD be `?`, unless it already has a defined meaning in the given database system, +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. + ## Semantic Conventions for specific database technologies More specific Semantic Conventions are defined for the following database technologies: diff --git a/docs/database/dynamodb.md b/docs/database/dynamodb.md index 2dedb607eb..eb342339f0 100644 --- a/docs/database/dynamodb.md +++ b/docs/database/dynamodb.md @@ -36,12 +36,9 @@ These attributes are filled in for all DynamoDB request types. | Value | Description | Stability | |---|---|---| | `adabas` | Adabas (Adaptable Database System) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cassandra` | Apache Cassandra | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `clickhouse` | ClickHouse | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cloudscape` | Cloudscape | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cockroachdb` | CockroachDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `coldfusion` | ColdFusion IMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cosmosdb` | Microsoft Azure Cosmos DB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `couchbase` | Couchbase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `couchdb` | CouchDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -52,7 +49,6 @@ These attributes are filled in for all DynamoDB request types. | `elasticsearch` | Elasticsearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `filemaker` | FileMaker | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `firebird` | Firebird | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `firstsql` | FirstSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `geode` | Apache Geode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `h2` | H2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `hanadb` | SAP HANA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -64,12 +60,12 @@ These attributes are filled in for all DynamoDB request types. | `ingres` | Ingres | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `instantdb` | InstantDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `interbase` | InterBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `intersystems_cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mariadb` | MariaDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `maxdb` | SAP MaxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mssql` | Microsoft SQL Server | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mssqlcompact` | Microsoft SQL Server Compact | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mysql` | MySQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `netezza` | Netezza | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 9e42fc98d1..d881f79ace 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -14,12 +14,7 @@ described on this page. ## Span Name -The **span name** SHOULD be of the format ``. - -The elasticsearch endpoint identifier is used instead of the url path in order to reduce the cardinality of the span -name, as the path could contain dynamic values. The endpoint id is the `name` field in the -[elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json). -If the endpoint id is not available, the span name SHOULD be the `http.request.method`. +The **span name** follows the [general database span name guidelines](database-spans.md#name) with the endpoint identifier stored in `db.operation.name`, and the index stored in `db.collection.name`. ## Attributes @@ -38,12 +33,13 @@ If the endpoint id is not available, the span name SHOULD be the `http.request.m | [`db.elasticsearch.path_parts.`](/docs/attributes-registry/db.md) | string | A dynamic value in the url path. [4] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | `Conditionally Required` when the url has dynamic values | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [5] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Conditionally Required` [7] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.elasticsearch.cluster.name`](/docs/attributes-registry/db.md) | string | Represents the identifier of an Elasticsearch cluster. | `e9106fc68e3044f0b1475b04bf4ffd5f` | `Recommended` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.elasticsearch.node.name`](/docs/attributes-registry/db.md) | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | `Recommended` [9] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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. [10] | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | `Recommended` [11] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The index or data stream against which the query is executed. [8] | `my_index`; `index1, index2` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.elasticsearch.node.name`](/docs/attributes-registry/db.md) | string | Represents the human-readable identifier of the node/instance to which a request was routed. [9] | `instance-0000000001` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the Elasticsearch cluster which the client connects to. [10] | `customers`; `test.users` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. [11] | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | `Recommended` [12] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [13] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** This SHOULD be the endpoint identifier for the request. +**[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)). **[2]:** 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) @@ -72,15 +68,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[7]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[8]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. +**[8]:** 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]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header. -**[10]:** 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. +**[10]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. + +**[11]:** 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. -**[11]:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information. +**[12]:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information. -**[12]:** 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]:** 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. @@ -117,16 +117,17 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original | Key | Value | |:------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------| -| Span name | `"search"` | +| Span name | `"search my-index"` | | `db.system` | `"elasticsearch"` | | `server.address` | `"elasticsearch.mydomain.com"` | | `server.port` | `9200` | | `http.request.method` | `"GET"` | | `db.query.text` | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | | `db.operation.name` | `"search"` | +| `db.collection.name` | `"my-index"` | | `url.full` | `"https://elasticsearch.mydomain.com:9200/my-index-000001/_search?from=40&size=20"` | | `db.elasticsearch.path_parts.index` | `"my-index-000001"` | -| `db.elasticsearch.cluster.name` | `"e9106fc68e3044f0b1475b04bf4ffd5f"` | -| `db.instance.id` | `"instance-0000000001"` | +| `db.namespace` | `"my-cluster"` | +| `db.elasticsearch.node.name` | `"instance-0000000001"` | [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/database/mssql.md b/docs/database/mssql.md index c345b60833..6962223af7 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -30,7 +30,7 @@ described on this page. | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Conditionally Required` [8] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. @@ -52,9 +52,11 @@ In the case of `EXEC`, this SHOULD be the stored procedure name that is being ex **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[9]:** 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. +**[9]:** 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. -**[10]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. +**[10]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). **[11]:** 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 9d1b5ef057..bbe41a21c2 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -31,7 +31,7 @@ described on this page. | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [9] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [11] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [11] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** The database index for current connection can be changed by the application dynamically. Instrumentations MAY use the initial database index provided in the connection string and keep track of the currently selected database to capture the `db.namespace`. Instrumentations SHOULD NOT set this attribute if capturing it would require additional network calls to Redis. diff --git a/docs/database/sql.md b/docs/database/sql.md index 46d4ba036a..524c5878bd 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -52,7 +52,7 @@ Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic co | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Conditionally Required` [8] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. @@ -91,9 +91,11 @@ In the case of `EXEC`, this SHOULD be the stored procedure name that is being ex **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[9]:** 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. +**[9]:** 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. -**[10]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. +**[10]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). **[11]:** 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/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 6613268bcf..4ed35e73f9 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -259,14 +259,15 @@ Function F: | Span ProcBatch | | Field or Attribute | Span Prod1 | Span Prod2 | Span ProcBatch | Span Proc1 | Span Proc2 | |-|-|-|-|-|-| -| Span name | `Q send` | `Q send` | `Q process` | `Q process` | `Q process` | +| Span name | `send Q` | `send Q` | `process Q` | `process Q` | `process Q` | | Parent | | | | Span ProcBatch | Span ProcBatch | | Links | | | | Span Prod1 | Span Prod2 | | SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` | `CONSUMER` | `CONSUMER` | | Status | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` | | `messaging.system` | `aws_sqs` | `aws_sqs` | `aws_sqs` | `aws_sqs` | `aws_sqs` | | `messaging.destination.name` | `Q` | `Q` | `Q` | `Q` | `Q` | -| `messaging.operation.type` | | | `process` | `process` | `process` | +| `messaging.operation.name` | `send` | `send` | `process` | `process` | `process` | +| `messaging.operation.type` | `publish` | `publish` | `process` | `process` | `process` | | `messaging.message.id` | | | | `"a1"` | `"a2"` | Note that if Span Prod1 and Span Prod2 were sent to different queues, Span ProcBatch would not have diff --git a/docs/gen-ai/README.md b/docs/gen-ai/README.md index 3bd772c58d..086a6d327f 100644 --- a/docs/gen-ai/README.md +++ b/docs/gen-ai/README.md @@ -14,16 +14,9 @@ The semantic conventions for GenAI and LLM are currently in development. We encourage instrumentation libraries and telemetry consumers developers to use the conventions in limited non-critical workloads and share the feedback -This document defines semantic conventions for the following kind of Generative AI systems: - -* LLMs - Semantic conventions for Generative AI operations are defined for the following signals: * [Metrics](gen-ai-metrics.md): Semantic Conventions for Generative AI operations - *metrics*. - -Semantic conventions for LLM operations are defined for the following signals: - -* [LLM Spans](llm-spans.md): Semantic Conventions for LLM requests - *spans*. +* [Spans](gen-ai-spans.md): Semantic Conventions for Generative AI requests - *spans*. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/gen-ai/gen-ai-metrics.md b/docs/gen-ai/gen-ai-metrics.md index 1d473dc924..800741360b 100644 --- a/docs/gen-ai/gen-ai-metrics.md +++ b/docs/gen-ai/gen-ai-metrics.md @@ -2,16 +2,10 @@ linkTitle: Generative AI metrics ---> -# Semantic Conventions for Generative AI Client Metrics +# Semantic Conventions for Generative AI Metrics **Status**: [Experimental][DocumentStatus] -The conventions described in this section are specific to Generative AI client -applications. - -**Disclaimer:** These are initial Generative AI client metric instruments -and attributes but more may be added in the future. - @@ -19,11 +13,21 @@ and attributes but more may be added in the future. - [Generative AI Client Metrics](#generative-ai-client-metrics) - [Metric: `gen_ai.client.token.usage`](#metric-gen_aiclienttokenusage) - [Metric: `gen_ai.client.operation.duration`](#metric-gen_aiclientoperationduration) +- [Generative AI Model Server Metrics](#generative-ai-model-server-metrics) + - [Metric: `gen_ai.server.request.duration`](#metric-gen_aiserverrequestduration) + - [Metric: `gen_ai.server.time_per_output_token`](#metric-gen_aiservertime_per_output_token) + - [Metric: `gen_ai.server.time_to_first_token`](#metric-gen_aiservertime_to_first_token) ## Generative AI Client Metrics +The conventions described in this section are specific to Generative AI client +applications. + +**Disclaimer:** These are initial Generative AI client metric instruments +and attributes but more may be added in the future. + The following metric instruments describe Generative AI operations. An operation may be a request to an LLM, a function call, or some other distinct action within a larger Generative AI workflow. @@ -67,20 +71,38 @@ 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. | `chat`; `completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the LLM a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.token.type`](/docs/attributes-registry/gen-ai.md) | string | The type of token being counted. | `input`; `output` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the LLM a response was generated from. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. +**[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. -**[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]:** 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. -**[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. +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +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. + +**[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. + + + +`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 | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `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. @@ -139,23 +161,133 @@ 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. | `chat`; `completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the LLM a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the LLM a response was generated from. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[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. + +**[2]:** 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. -**[1]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. -**[2]:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, +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, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. -**[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. +**[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. + +**[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. + + + +`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +`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 | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +`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 | +|---|---|---| +| `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + -**[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. + + + + + + +## Generative AI Model Server Metrics + +The following metric instruments describe Generative AI model servers' +operational metrics. It includes both functional and performance metrics. + +### Metric: `gen_ai.server.request.duration` + +This metric is [recommended][MetricRecommended] to report the model server +latency in terms of time spent per request. + +This metric SHOULD be specified with [ExplicitBucketBoundaries] of +[0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12,10.24, 20.48, 40.96, 81.92]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `gen_ai.server.request.duration` | Histogram | `s` | Generative AI server request duration such as time-to-last byte or last output token | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + + + + + + + +| 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[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. + +**[2]:** 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. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +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, +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. + +**[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. @@ -166,6 +298,189 @@ Instrumentations SHOULD document the list of errors they report. | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +`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 | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +`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 | +|---|---|---| +| `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `gen_ai.server.time_per_output_token` + +This metric is [recommended][MetricRecommended] to report the model server +latency in terms of time per token generated after the first token for any model +servers which support serving LLMs. It is measured by subtracting the time taken +to generate the first output token from the request duration and dividing the +rest of the duration by the number of output tokens generated after the first +token. This is important in measuring the performance of the decode phase of LLM +inference. + +This metric SHOULD be specified with [ExplicitBucketBoundaries] of +[0.01, 0.025, 0.05, 0.075, 0.1, 0.15, 0.2, 0.3, 0.4, 0.5, 0.75, 1.0, 2.5]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `gen_ai.server.time_per_output_token` | Histogram | `s` | Time per output token generated after the first token for successful responses | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + + + + + + + +| 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[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. + +**[2]:** 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. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +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. + +**[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. + + + +`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 | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +`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 | +|---|---|---| +| `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `gen_ai.server.time_to_first_token` + +This metric is [recommended][MetricRecommended] to report the model server +latency in terms of time spent to generate the first token of the response for +any model servers which support serving LLMs. It helps measure the time spent in +the queue and the prefill phase. It is important especially for streaming +requests. It is calculated at a request level and is reported as a histogram +using the buckets mentioned below. + +This metric SHOULD be specified with [ExplicitBucketBoundaries] of +[0.001, 0.005, 0.01, 0.02, 0.04, 0.06, 0.08, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `gen_ai.server.time_to_first_token` | Histogram | `s` | Time to generate first token for successful responses | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + + + + + + + +| 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[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. + +**[2]:** 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. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +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. + +**[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. + + + +`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 | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + `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 | @@ -185,4 +500,4 @@ Instrumentations SHOULD document the list of errors they report. [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.31.0/specification/metrics/api.md#instrument-advisory-parameters +[ExplicitBucketBoundaries]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.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 new file mode 100644 index 0000000000..e50cd6a05d --- /dev/null +++ b/docs/gen-ai/gen-ai-spans.md @@ -0,0 +1,160 @@ + + +# Semantic Conventions for GenAI operations + +**Status**: [Experimental][DocumentStatus] + + + + + +- [Name](#name) +- [Configuration](#configuration) +- [GenAI attributes](#genai-attributes) +- [Events](#events) + + + +A request to an Generative AI is modeled as a span in a trace. + +**Span kind:** MUST always be `CLIENT`. + +## Name + +GenAI spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.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. + +## Configuration + +Instrumentations for Generative AI clients MAY capture prompts and completions. +Instrumentations that support it, MUST offer the ability to turn off capture of prompts and completions. This is for three primary reasons: + +1. Data privacy concerns. End users of GenAI applications may input sensitive information or personally identifiable information (PII) that they do not wish to be sent to a telemetry backend. +2. Data size concerns. Although there is no specified limit to sizes, there are practical limitations in programming languages and telemetry systems. Some GenAI systems allow for extremely large context windows that end users may take full advantage of. +3. Performance concerns. Sending large amounts of data to a telemetry backend may cause performance issues for the application. + +## 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. + + + + + + + + +| 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [3] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.presence_penalty`](/docs/attributes-registry/gen-ai.md) | double | The presence penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.stop_sequences`](/docs/attributes-registry/gen-ai.md) | string[] | List of sequences that the model will use to stop generating further tokens. | `["forest", "lived"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.temperature`](/docs/attributes-registry/gen-ai.md) | double | The temperature setting for the GenAI request. | `0.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.top_k`](/docs/attributes-registry/gen-ai.md) | double | The top_k sampling setting for the GenAI request. | `1.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the GenAI request. | `1.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [4] | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI input (prompt). | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI response (completion). | `180` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[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. + +**[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. + +**[3]:** 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. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +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`. + +**[4]:** 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. + + + +`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 | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +`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 | +|---|---|---| +| `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +## Events + +In the lifetime of a GenAI span, an event for prompts sent and completions received MAY be created, depending on the configuration of the instrumentation. + + + + + + + + +The event name MUST be `gen_ai.content.prompt`. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.prompt`](/docs/attributes-registry/gen-ai.md) | string | The full prompt sent to the GenAI model. [1] | `[{'role': 'user', 'content': 'What is the capital of France?'}]` | `Conditionally Required` if and only if corresponding event is enabled | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + + + + + + + + + + + + + + + + +The event name MUST be `gen_ai.content.completion`. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.completion`](/docs/attributes-registry/gen-ai.md) | string | The full response received from the GenAI model. [1] | `[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]` | `Conditionally Required` if and only if corresponding event is enabled | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + + + + + + + + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/gen-ai/llm-spans.md b/docs/gen-ai/llm-spans.md deleted file mode 100644 index 2106d6d40e..0000000000 --- a/docs/gen-ai/llm-spans.md +++ /dev/null @@ -1,133 +0,0 @@ - - -# Semantic Conventions for LLM requests - -**Status**: [Experimental][DocumentStatus] - - - - - -- [Configuration](#configuration) -- [LLM Request attributes](#llm-request-attributes) -- [Events](#events) - - - -A request to an LLM is modeled as a span in a trace. - -**Span kind:** MUST always be `CLIENT`. - -The **span name** SHOULD be set to a low cardinality value describing an operation made to an LLM. -For example, the API name such as [Create chat completion](https://platform.openai.com/docs/api-reference/chat/create) could be represented as `ChatCompletions gpt-4` to include the API and the LLM. - -## Configuration - -Instrumentations for LLMs MAY capture prompts and completions. -Instrumentations that support it, MUST offer the ability to turn off capture of prompts and completions. This is for three primary reasons: - -1. Data privacy concerns. End users of LLM applications may input sensitive information or personally identifiable information (PII) that they do not wish to be sent to a telemetry backend. -2. Data size concerns. Although there is no specified limit to sizes, there are practical limitations in programming languages and telemetry systems. Some LLMs allow for extremely large context windows that end users may take full advantage of. -3. Performance concerns. Sending large amounts of data to a telemetry backend may cause performance issues for the application. - -## LLM Request attributes - -These attributes track input data and metadata for a request to an LLM. Each attribute represents a concept that is common to most LLMs. - - - - - - - - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the LLM a request is being made to. [1] | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the LLM generates for a request. | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.request.temperature`](/docs/attributes-registry/gen-ai.md) | double | The temperature setting for the LLM request. | `0.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the LLM request. | `1.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the LLM a response was generated from. [3] | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.usage.completion_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the LLM response (completion). | `180` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.usage.prompt_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the LLM prompt. | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** The name of the LLM a request is being made to. If the LLM is supplied by a vendor, then the value must be the exact name of the model requested. If the LLM is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. - -**[2]:** If not using a vendor-supplied model, provide a custom friendly name, such as a name of the company or project. If the instrumetnation reports any attributes specific to a custom model, the value provided in the `gen_ai.system` SHOULD match the custom attribute namespace segment. For example, if `gen_ai.system` is set to `the_best_llm`, custom attributes should be added in the `gen_ai.the_best_llm.*` namespace. If none of above options apply, the instrumentation should set `_OTHER`. - -**[3]:** If available. The name of the LLM serving a response. If the LLM is supplied by a vendor, then the value must be the exact name of the model actually used. If the LLM is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. - - - -`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 | -|---|---|---| -| `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - - - - - - - - -## Events - -In the lifetime of an LLM span, an event for prompts sent and completions received MAY be created, depending on the configuration of the instrumentation. - - - - - - - - -The event name MUST be `gen_ai.content.prompt`. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`gen_ai.prompt`](/docs/attributes-registry/gen-ai.md) | string | The full prompt sent to an LLM. [1] | `[{'role': 'user', 'content': 'What is the capital of France?'}]` | `Conditionally Required` if and only if corresponding event is enabled | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) - - - - - - - - - - - - - - - - -The event name MUST be `gen_ai.content.completion`. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`gen_ai.completion`](/docs/attributes-registry/gen-ai.md) | string | The full response received from the LLM. [1] | `[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]` | `Conditionally Required` if and only if corresponding event is enabled | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) - - - - - - - - - -[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/general/attribute-naming.md b/docs/general/attribute-naming.md index c45a92e1bf..3b3445cb46 100644 --- a/docs/general/attribute-naming.md +++ b/docs/general/attribute-naming.md @@ -7,7 +7,8 @@ -- [Name Pluralization guidelines](#name-pluralization-guidelines) +- [Name Pluralization Guidelines](#name-pluralization-guidelines) +- [Name Abbreviation Guidelines](#name-abbreviation-guidelines) - [Name Reuse Prohibition](#name-reuse-prohibition) - [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors) - [Recommendations for Application Developers](#recommendations-for-application-developers) @@ -57,7 +58,7 @@ Names SHOULD follow these rules: versa: any existing namespace prohibits existence of an equally named attribute key in the future. -## Name Pluralization guidelines +## Name Pluralization Guidelines - When an attribute represents a single entity, the attribute name SHOULD be singular. Examples: `host.name`, `container.id`. @@ -70,6 +71,16 @@ Names SHOULD follow these rules: [Metric Name Pluralization Guidelines](./metrics.md#pluralization) SHOULD be followed for the attribute name. +## Name Abbreviation Guidelines + +Abbreviations MAY be used when they are widely recognized and commonly used. + +Examples include common technical abbreviations such as `IP`, `DB`, `CPU`, +`HTTP`, `URL`, or product names like `AWS`, `GCP`, `K8s`. + +Abbreviations SHOULD be avoided if they are ambiguous, for example, when they apply +to multiple products or concepts. + ## Name Reuse Prohibition A new attribute MUST NOT be added with the same name as an attribute that diff --git a/docs/general/logs.md b/docs/general/logs.md index e7e649cde1..499b719841 100644 --- a/docs/general/logs.md +++ b/docs/general/logs.md @@ -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.33.0/specification/resource/sdk.md#resource-sdk) 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.33.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 6dffdaa3d5..09892e5fc0 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -82,6 +82,9 @@ and confusion for end users. (For example, prefer `process.runtime.java.gc*` ove `process.runtime.gc.*`.) Measures of many operating system metrics are similarly ambiguous. +Metric names and attributes SHOULD follow the general +[name abbreviation guidelines](attribute-naming.md#name-abbreviation-guidelines). + ### Name Reuse Prohibition A new metric MUST NOT be added with the same name as a metric that existed in diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 180d595d41..a22e33506b 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -93,19 +93,31 @@ Instrumentation MUST NOT default to using URI path as a `{target}`. the response body; or 3xx codes with max redirects exceeded), in which case status MUST be set to `Error`. +> **Note:** +> +> The classification of an HTTP status code as an error depends on the context. +> For example, a 404 "Not Found" status code indicates an error if the application +> expected the resource to be available. However, it is not an error when the +> application is simply checking whether the resource exists. +> +> Instrumentations that have additional context about a specific request 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. + For HTTP status codes in the 4xx range span status MUST be left unset in case of `SpanKind.SERVER` -and MUST be set to `Error` in case of `SpanKind.CLIENT`. +and SHOULD be set to `Error` in case of `SpanKind.CLIENT`. For HTTP status codes in the 5xx range, as well as any other code the client -failed to interpret, span status MUST be set to `Error`. +failed to interpret, span status SHOULD be set to `Error`. Don't set the span status description if the reason can be inferred from `http.response.status_code`. HTTP request may fail if it was cancelled or an error occurred preventing the client or server from sending/receiving the request/response fully. -When instrumentation detects such errors it MUST set span status to `Error` -and MUST set the `error.type` attribute. +When instrumentation detects such errors it SHOULD set span status to `Error` +and SHOULD set the `error.type` attribute. ## HTTP client diff --git a/docs/messaging/README.md b/docs/messaging/README.md index bbbccefc3d..ba5ab92a3a 100644 --- a/docs/messaging/README.md +++ b/docs/messaging/README.md @@ -22,5 +22,7 @@ Technology specific semantic conventions are defined for the following messaging * [RabbitMQ](rabbitmq.md): Semantic Conventions for *RabbitMQ*. * [RocketMQ](rocketmq.md): Semantic Conventions for *Apache RocketMQ*. * [Google Cloud Pub/Sub](gcp-pubsub.md): Semantic Conventions for *Google Cloud Pub/Sub*. +* [Azure Service Bus](azure-messaging.md#azure-service-bus): Semantic Conventions for *Azure Service Bus*. +* [Azure Event Hubs](azure-messaging.md#azure-event-hubs): Semantic Conventions for *Azure Event Hubs*. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md index 5a4dcd11fd..0d2d6e4e7d 100644 --- a/docs/messaging/azure-messaging.md +++ b/docs/messaging/azure-messaging.md @@ -2,7 +2,7 @@ linkTitle: Azure Messaging ---> -# Semantic Conventions for Azure Messaging systems +# Semantic Conventions for Azure Messaging Systems **Status**: [Experimental][DocumentStatus] @@ -10,7 +10,7 @@ The Semantic Conventions for [Azure Service Bus](https://learn.microsoft.com/azu ## Azure Service Bus -`messaging.system` MUST be set to `"servicebus"`. +`messaging.system` MUST be set to `"servicebus"` and SHOULD be provided **at span creation time**. ### Span attributes @@ -24,21 +24,30 @@ The following additional attributes are defined: | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [1] | `publish`; `create`; `receive` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | Azure Service Bus operation name. [1] | `send`; `receive`; `complete`; `process`; `peek` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [5] | `MyQueue`; `MyTopic` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.servicebus.destination.subscription_name`](/docs/attributes-registry/messaging.md) | string | The name of the subscription in the topic messages are received from. | `mySubscription` | `Conditionally Required` If messages are received from the subscription. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | Azure Service Bus [subscription name](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-queues-topics-subscriptions#topics-and-subscriptions). | `subscription-a` | `Conditionally Required` If messages are received from the subscription. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `publish`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.servicebus.disposition_status`](/docs/attributes-registry/messaging.md) | string | Describes the [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). | `complete`; `abandon`; `dead_letter` | `Conditionally Required` if and only if `messaging.operation` is `settle`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.servicebus.message.delivery_count`](/docs/attributes-registry/messaging.md) | int | Number of deliveries that have been attempted for this message. | `2` | `Conditionally Required` [7] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`messaging.servicebus.message.delivery_count`](/docs/attributes-registry/messaging.md) | int | Number of deliveries that have been attempted for this message. | `2` | `Conditionally Required` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.message.conversation_id`](/docs/attributes-registry/messaging.md) | string | Message [correlation Id](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-messages-payloads#message-routing-and-correlation) property. | `MyConversationId` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | `Recommended` [9] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** If a custom value is used, it MUST be of low cardinality. +**[1]:** The operation name SHOULD match one of the following values: + +- sender operations: `send`, `schedule`, `cancel_scheduled` +- transaction operations: `create_transaction`, `commit_transaction`, `rollback_transaction` +- receiver operation: `receive`, `peek`, `receive_deferred`, `renew_message_lock` +- settlement operations: `abandon`, `complete`, `defer`, `dead_letter`, `delete` +- session operations: `accept_session`, `get_session_state`, `set_session_state`, `renew_session_lock` + +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. @@ -69,16 +78,26 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi **[6]:** If span describes operation on a single message or if the value applies to all messages in the batch. -**[7]:** If delivery count is available and is bigger than 0. +**[7]:** 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]:** If delivery count is available and is bigger than 0. -**[9]:** If the operation is not sufficiently described by `messaging.operation.type`. +**[9]:** 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. +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`messaging.destination.name`](/docs/attributes-registry/messaging.md) +* [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) +* [`messaging.operation.name`](/docs/attributes-registry/messaging.md) +* [`messaging.operation.type`](/docs/attributes-registry/messaging.md) +* [`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 | @@ -91,7 +110,7 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi | Value | Description | Stability | |---|---|---| | `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `process` | One or more messages are delivered to or processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process` | One or more messages are processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `settle` | One or more messages are settled. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -115,7 +134,7 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi ## Azure Event Hubs -`messaging.system` MUST be set to `"eventhubs"`. +`messaging.system` MUST be set to `"eventhubs"` and SHOULD be provided **at span creation time**. ### Span attributes @@ -129,19 +148,29 @@ The following additional attributes are defined: | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [1] | `publish`; `create`; `receive` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | Azure Event Hubs operation name. [1] | `send`; `receive`; `checkpoint` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [5] | `MyQueue`; `MyTopic` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.eventhubs.consumer.group`](/docs/attributes-registry/messaging.md) | string | The name of the consumer group the event consumer is associated with. | `indexer` | `Conditionally Required` If not default ("$Default"). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `publish`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.eventhubs.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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | `Recommended` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [9] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** If a custom value is used, it MUST be of low cardinality. +**[1]:** The operation name SHOULD match one of the following values: + +- `send` +- `receive` +- `process` +- `checkpoint` +- `get_partition_properties` +- `get_event_hub_properties` + +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. @@ -172,14 +201,25 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi **[6]:** If span describes operation on a single message or if the value applies to all messages in the batch. -**[7]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. +**[7]:** If a custom value is used, it MUST be of low cardinality. -**[8]:** If the operation is not sufficiently described by `messaging.operation.type`. +**[8]:** 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. +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) +* [`messaging.destination.name`](/docs/attributes-registry/messaging.md) +* [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) +* [`messaging.operation.name`](/docs/attributes-registry/messaging.md) +* [`messaging.operation.type`](/docs/attributes-registry/messaging.md) +* [`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 | @@ -192,7 +232,7 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi | Value | Description | Stability | |---|---|---| | `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `process` | One or more messages are delivered to or processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process` | One or more messages are processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `settle` | One or more messages are settled. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md index a4987234db..1957e3dbbc 100644 --- a/docs/messaging/gcp-pubsub.md +++ b/docs/messaging/gcp-pubsub.md @@ -8,7 +8,7 @@ linkTitle: Google Cloud Pub/Sub The Semantic Conventions for [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) extend and override the [Messaging Semantic Conventions](README.md) that describe common messaging operations attributes in addition to the Semantic Conventions described on this page. -`messaging.system` MUST be set to `"gcp_pubsub"`. +`messaging.system` MUST be set to `"gcp_pubsub"` and SHOULD be provided **at span creation time**. ## Span attributes @@ -23,20 +23,28 @@ For Google Cloud Pub/Sub, the following additional attributes are defined: | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [1] | `publish`; `create`; `receive` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. [1] | `ack`; `nack`; `send` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [5] | `MyQueue`; `MyTopic` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.gcp_pubsub.message.ordering_key`](/docs/attributes-registry/messaging.md) | string | The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. | `ordering_key` | `Conditionally Required` If the message type has an ordering key set. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `publish`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | Google Pub/Sub [subscription name](https://cloud.google.com/pubsub/docs/subscription-overview). | `subscription-a` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.gcp_pubsub.message.ack_deadline`](/docs/attributes-registry/messaging.md) | int | The ack deadline in seconds set for the modify ack deadline request. | `10` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.gcp_pubsub.message.ack_id`](/docs/attributes-registry/messaging.md) | string | The ack id for a given message. | `ack_id` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.gcp_pubsub.message.delivery_attempt`](/docs/attributes-registry/messaging.md) | int | The delivery attempt for a given message. | `2` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | `Recommended` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [9] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** If a custom value is used, it MUST be of low cardinality. +**[1]:** 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 +- `send` for publishing operations +- `modack` for extending the lease for a single message or batch of messages +- `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#common-messaging-operations) **[2]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. @@ -67,14 +75,24 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi **[6]:** If span describes operation on a single message or if the value applies to all messages in the batch. -**[7]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. +**[7]:** If a custom value is used, it MUST be of low cardinality. -**[8]:** If the operation is not sufficiently described by `messaging.operation.type`. +**[8]:** 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. +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`messaging.destination.name`](/docs/attributes-registry/messaging.md) +* [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) +* [`messaging.operation.name`](/docs/attributes-registry/messaging.md) +* [`messaging.operation.type`](/docs/attributes-registry/messaging.md) +* [`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 | @@ -87,7 +105,7 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi | Value | Description | Stability | |---|---|---| | `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `process` | One or more messages are delivered to or processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process` | One or more messages are processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `settle` | One or more messages are settled. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -99,19 +117,6 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi -## Span names - -The span name SHOULD follow the [general messaging span name pattern](../messaging/gcp-pubsub.md): it SHOULD start with the messaging destination name (Topic/Subscription) and contain a low-cardinality name of an operation the span describes: - -- Spans for `settle` operations SHOULD follow the ` ack` or ` nack` pattern. -- Spans names for `publish` operations SHOULD follow the ` send` pattern. -- Spans for `create`, `receive`, and `publish` operations SHOULD follow the general ` ` pattern. - -In addition there are the following operations are GCP specific: - -- Spans that represents the time from after the message was received to when the message is acknowledged, negatively acknowledged, or expire (used by streaming pull) SHOULD follow the ` subscribe` pattern. -- Spans that represent extending the lease for a single message or batch of messages SHOULD follow the` modack` pattern. - ## Examples ### Asynchronous Batch Publish Example @@ -138,13 +143,14 @@ flowchart LR; | Field or Attribute | Span Create A | Span Create B | Span Publish A B | |-|-|-|-| -| Span name | `T create` | `T create` | `publish` | +| Span name | `create T` | `create T` | `send T` | | Parent | | | | | Links | | | Span Create A, Span Create B | | SpanKind | `PRODUCER` | `PRODUCER` | `CLIENT` | | Status | `Ok` | `Ok` | `Ok` | | `messaging.batch.message_count` | | | 2 | | `messaging.destination.name` | `"T"` | `"T"` | `"T"` | +| `messaging.operation.name` | `"create"` | `"create"` | `"send"` | | `messaging.operation.type` | `"create"` | `"create"` | `"publish"` | | `messaging.message.id` | `"a1"` | `"a2"` | | | `messaging.message.envelope.size` | `1` | `1` | | @@ -196,14 +202,15 @@ flowchart TD; | Field or Attribute | Span Create A | Span Publish A | Span Receive A | Span Modack A | Span Ack A | |-|-|-|-|-|-| -| Span name | `T create` | `publish` | `S receive` | `S modack` |`S ack` | +| Span name | `create T` | `send T` | `receive S` | `modack S` | `ack S` | | Parent | | | | | | | Links | | Span Create A | Span Create A | Span Receive A | Span Receive A | | SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` |`CLIENT` |`CLIENT` | | Status | `Ok` | `Ok` | `Ok` |`Ok` | `Ok` | | `messaging.destination.name` | `"T"`| `"T"`| `"S"` | `"S"` |`"S"` | | `messaging.system` | `"gcp_pubsub"` | `"gcp_pubsub"` | `"gcp_pubsub"` | `"gcp_pubsub"` | `"gcp_pubsub"` | -| `messaging.operation` | `"create"` | `"publish"` | `"receive"` | `"extend"` | `"settle"` | +| `messaging.operation.name` | `"create"` | `"send"` | `"receive"` | `"modack"` | `"ack"` | +| `messaging.operation.type` | `"create"` | `"publish"` | `"receive"` | | `"settle"` | | `messaging.message.id` | `"a1"` | | `"a1"` | | | | `messaging.message.envelope.size` | `1` | `1` | `1` | | | | `messaging.gcp_pubsub.message.ack_id` | | | | `"ack_id1"` |`"ack_id1"` | diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index d7bdf3953a..14b01a072d 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -18,7 +18,7 @@ The Semantic Conventions for [Apache Kafka](https://kafka.apache.org/) extend an that describe common messaging operations attributes in addition to the Semantic Conventions described on this page. -`messaging.system` MUST be set to `"kafka"`. +`messaging.system` MUST be set to `"kafka"` and SHOULD be provided **at span creation time**. ## Span attributes @@ -33,25 +33,23 @@ For Apache Kafka, the following additional attributes are defined: | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [1] | `publish`; `create`; `receive` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [5] | `MyQueue`; `MyTopic` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.kafka.message.tombstone`](/docs/attributes-registry/messaging.md) | boolean | A boolean that is true if the message is a tombstone. | | `Conditionally Required` [7] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | `Conditionally Required` If and only if the messaging operation has failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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. [2] | `0`; `1`; `2` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [4] | `MyQueue`; `MyTopic` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.kafka.message.tombstone`](/docs/attributes-registry/messaging.md) | boolean | A boolean that is true if the message is a tombstone. | | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `publish`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.client.id`](/docs/attributes-registry/messaging.md) | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) | string | Kafka [consumer group id](https://docs.confluent.io/platform/current/clients/consumer.html). | `my-group`; `indexer` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | String representation of the partition id the message (or batch) is sent to or received from. | `1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.kafka.consumer.group`](/docs/attributes-registry/messaging.md) | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.kafka.message.key`](/docs/attributes-registry/messaging.md) | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [9] | `myKey` | `Recommended` If span describes operation on a single message. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.kafka.message.offset`](/docs/attributes-registry/messaging.md) | int | The offset of a record in the corresponding Kafka partition. | `42` | `Recommended` If span describes operation on a single message. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. [10] | `1439` | `Recommended` If span describes operation on a single message. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | `Recommended` [11] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [12] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [11] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** If a custom value is used, it MUST be of low cardinality. - -**[2]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. +**[1]:** 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. @@ -71,16 +69,18 @@ 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. +**[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. -**[4]:** If the span describes an operation on a batch of messages. +**[3]:** 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 +**[4]:** 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. +**[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 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. **[8]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. @@ -89,11 +89,20 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi **[10]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed body size should be used. -**[11]:** If the operation is not sufficiently described by `messaging.operation.type`. +**[11]:** 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. + -**[12]:** 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): +* [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) +* [`messaging.destination.name`](/docs/attributes-registry/messaging.md) +* [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) +* [`messaging.operation.name`](/docs/attributes-registry/messaging.md) +* [`messaging.operation.type`](/docs/attributes-registry/messaging.md) +* [`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. @@ -107,7 +116,7 @@ body size should be used. | Value | Description | Stability | |---|---|---| | `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `process` | One or more messages are delivered to or processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process` | One or more messages are processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `settle` | One or more messages are settled. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -129,40 +138,50 @@ If an intermediary broker is present, `service.name` and `peer.service` will not ### Apache Kafka with Quarkus or Spring Boot Example -Given is a process P, that publishes a message to a topic T1 on Apache Kafka. -One process, CA, receives the message and publishes a new message to a topic T2 that is then received and processed by CB. - -Frameworks such as Quarkus and Spring Boot separate processing of a received message from producing subsequent messages out. -For this reason, receiving (Span Rcv1) is the parent of both processing (Span Proc1) and producing a new message (Span Prod2). -The span representing message receiving (Span Rcv1) should not set `messaging.operation.type` to `receive`, -as it does not only receive the message but also converts the input message to something suitable for the processing operation to consume and creates the output message from the result of processing. - -``` -Process P: | Span Prod1 | --- -Process CA: | Span Rcv1 | - | Span Proc1 | - | Span Prod2 | --- -Process CB: | Span Rcv2 | +In this example, the producer publishes a message to a topic T on Apache Kafka. +Consumer receives the message, processes it and commits the offset. + +Frameworks such as Quarkus and Spring Boot provide integrations with Kafka allowing to +configure and instrument processing callbacks, so corresponding instrumentations should create "Process" +spans in addition to "Receive" spans created by Kafka instrumentations for polling calls. + +```mermaid +flowchart LR; + subgraph PRODUCER + P[Span Send] + end + subgraph CONSUMER + direction TB + R1[Span Poll] + R2[Span Process] + R3[Span Commit] + end + + P-. link .-R1; + P-. link .-R2; + R2-- parent ---R3; + + classDef normal fill:green + class P,R1,R2,R3 normal + linkStyle 0 color:green,stroke:green + linkStyle 1 color:green,stroke:green ``` -| Field or Attribute | Span Prod1 | Span Rcv1 | Span Proc1 | Span Prod2 | Span Rcv2 | -|-|-|-|-|-|-| -| Span name | `"T1 publish"` | `"T1 receive"` | `"T1 process"` | `"T2 publish"` | `"T2 receive`" | -| Parent | | Span Prod1 | Span Rcv1 | Span Rcv1 | Span Prod2 | -| Links | | | | | | -| SpanKind | `PRODUCER` | `CONSUMER` | `CONSUMER` | `PRODUCER` | `CONSUMER` | -| Status | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` | -| `peer.service` | `"myKafka"` | | | `"myKafka"` | | -| `service.name` | | `"myConsumer1"` | `"myConsumer1"` | | `"myConsumer2"` | -| `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | -| `messaging.destination.name` | `"T1"` | `"T1"` | `"T1"` | `"T2"` | `"T2"` | -| `messaging.operation.type` | | | `"process"` | | `"receive"` | -| `messaging.client.id` | | `"5"` | `"5"` | `"5"` | `"8"` | -| `messaging.kafka.message.key` | `"myKey"` | `"myKey"` | `"myKey"` | `"anotherKey"` | `"anotherKey"` | -| `messaging.kafka.consumer.group` | | `"my-group"` | `"my-group"` | | `"another-group"` | -| `messaging.kafka.destination.partition` | `"1"` | `"1"` | `"1"` | `"3"` | `"3"` | -| `messaging.kafka.message.offset` | `"12"` | `"12"` | `"12"` | `"32"` | `"32"` | +| Field or Attribute | Span Send | Span Poll | Span Process | Span Commit T | +|-|-|-|-|-| +| Span name | `"send T"` | `"poll T"` | `"process T"` | `"commit T"` | +| Parent | | | (optional) Span Send | Span Process | +| Links | | Span Send | Span Send | | +| SpanKind | `PRODUCER` | `CONSUMER` | `SERVER` | `CLIENT` | +| Status | `UNSET` | `UNSET` | `UNSET` | `UNSET` | +| `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | +| `messaging.destination.name` | `"T"` | `"T"` | `"T"` | `"T"` | +| `messaging.destination.consumer.group` | | `"my-group"` | `"my-group"` | `"my-group"` | +| `messaging.destination.partition.id` | `"1"` | `"1"` | `"1"` | `"1"` | +| `messaging.operation.name` | `"send"` | `"poll"` | `"process"` | `"commit"` | +| `messaging.operation.type` | `"publish"` | `"receive"` | `"process"` | `"settle"` | +| `messaging.client.id` | `"5"` | `"8"` | `"8"` | `"8"` | +| `messaging.kafka.message.key` | `"myKey"` | `"myKey"` | `"myKey"` | | +| `messaging.kafka.message.offset` | | `"12"` | `"12"` | `"12"` | [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md index dcc7b6c0f4..a50c3f38d5 100644 --- a/docs/messaging/messaging-metrics.md +++ b/docs/messaging/messaging-metrics.md @@ -1,4 +1,4 @@ -# Semantic Conventions for Messaging Metrics +# Semantic Conventions for Messaging Client Metrics **Status**: [Experimental][DocumentStatus] @@ -6,15 +6,13 @@ -- [Common attributes](#common-attributes) +- [Common metrics](#common-metrics) + - [Metric: `messaging.client.operation.duration`](#metric-messagingclientoperationduration) - [Producer metrics](#producer-metrics) - - [Metric: `messaging.publish.duration`](#metric-messagingpublishduration) - - [Metric: `messaging.publish.messages`](#metric-messagingpublishmessages) + - [Metric: `messaging.client.published.messages`](#metric-messagingclientpublishedmessages) - [Consumer metrics](#consumer-metrics) - - [Metric: `messaging.receive.duration`](#metric-messagingreceiveduration) - - [Metric: `messaging.receive.messages`](#metric-messagingreceivemessages) + - [Metric: `messaging.client.consumed.messages`](#metric-messagingclientconsumedmessages) - [Metric: `messaging.process.duration`](#metric-messagingprocessduration) - - [Metric: `messaging.process.messages`](#metric-messagingprocessmessages) @@ -25,11 +23,40 @@ > until a transition plan to the (future) stable semantic conventions has been published. > Conventions include, but are not limited to, attributes, metric and span names, and unit of measure. -## Common attributes +## Common metrics -All messaging metrics share the same set of attributes: +### Metric: `messaging.client.operation.duration` - +When this metric is reported alongside a messaging span, the metric value SHOULD be the same as the corresponding span duration. + +This metric is [required][MetricRequired]. + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/metrics/api.md#instrument-advice) +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 ]`. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `messaging.client.operation.duration` | Histogram | `s` | Duration of messaging operation initiated by a producer or consumer client. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** This metric SHOULD NOT be used to report processing duration - processing duration is reported in `messaging.process.duration` metric. + + + + + + + + + @@ -38,13 +65,17 @@ All messaging metrics share the same set of attributes: | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| +| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `send`; `receive`; `ack` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.system`](/docs/attributes-registry/messaging.md) | string | The messaging system as identified by the client instrumentation. [1] | `activemq`; `aws_sqs`; `eventgrid` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [3] | `MyQueue`; `MyTopic` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.destination.template`](/docs/attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [5] | `/customers/{customerId}` | `Conditionally Required` if available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) | string | The name of the consumer group with which a consumer is associated. [3] | `my-group`; `indexer` | `Conditionally Required` if applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [4] | `MyQueue`; `MyTopic` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | The name of the destination subscription from which a message is consumed. [6] | `subscription-a` | `Conditionally Required` if applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.template`](/docs/attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [7] | `/customers/{customerId}` | `Conditionally Required` if available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [8] | `publish`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[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. @@ -68,16 +99,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]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If +**[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. + +**[4]:** 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]:** 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. +**[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]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. +**[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]:** 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 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. + +**[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. @@ -88,6 +125,17 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +`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 | +|---|---|---| +| `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process` | One or more messages are processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `settle` | One or more messages are settled. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + `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 | @@ -113,17 +161,11 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi ## Producer metrics -### Metric: `messaging.publish.duration` +### Metric: `messaging.client.published.messages` This metric is [required][MetricRequired]. -When this metric is reported alongside a messaging publish span, the metric value SHOULD be the same as the corresponding span duration. - -This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/metrics/api.md#instrument-advice) -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 ]`. - - + @@ -132,7 +174,11 @@ 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 | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `messaging.publish.duration` | Histogram | `s` | Measures the duration of publish operation. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.client.published.messages` | Counter | `{message}` | Number of messages producer attempted to publish to the broker. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** This metric MUST NOT count messages that were created haven't yet been attempted to be published. + @@ -140,20 +186,82 @@ 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: `messaging.publish.messages` - -This metric is [required][MetricRequired] when the messaging system supports batch publishing. It's [opt-in][MetricOptIn] when the messaging system does not support batch publishing, since the message count can be derived from the `messaging.publish.duration` histogram. - - + -| Name | Instrument Type | Unit (UCUM) | Description | Stability | -| -------- | --------------- | ----------- | -------------- | --------- | -| `messaging.publish.messages` | Counter | `{message}` | Measures the number of published messages. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `send`; `schedule`; `enqueue` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.system`](/docs/attributes-registry/messaging.md) | string | The messaging system as identified by the client instrumentation. [1] | `activemq`; `aws_sqs`; `eventgrid` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [3] | `MyQueue`; `MyTopic` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.template`](/docs/attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [5] | `/customers/{customerId}` | `Conditionally Required` if available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[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. + +**[2]:** 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. + +**[3]:** 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. + +**[6]:** 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. + + + +`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +`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 | +|---|---|---| +| `activemq` | Apache ActiveMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws_sqs` | Amazon Simple Queue Service (SQS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `eventgrid` | Azure Event Grid | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `eventhubs` | Azure Event Hubs | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp_pubsub` | Google Cloud Pub/Sub | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `jms` | Java Message Service | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `kafka` | Apache Kafka | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pulsar` | Apache Pulsar | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rabbitmq` | RabbitMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rocketmq` | Apache RocketMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `servicebus` | Azure Service Bus | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + @@ -161,21 +269,13 @@ This metric is [required][MetricRequired] when the messaging system supports bat -> The need to report `messaging.publish.messages` depends on the messaging system capabilities and not application scenarios or client library limitations. For example, RabbitMQ does not support batch publishing and corresponding instrumentations don't need to report `messaging.publish.messages`. Kafka supports both, single and batch publishing, and instrumentations MUST report `messaging.publish.messages` counter regardless of application scenarios or APIs available in the client library. - ## Consumer metrics -### Metric: `messaging.receive.duration` - -This metric is [required][MetricRequired] for operations that are initiated by the application code (pull-based). - -This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/metrics/api.md#instrument-advice) -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: `messaging.client.consumed.messages` -When this metric is reported alongside a messaging receive span, the metric value SHOULD be the same as the corresponding span duration. +This metric is [required][MetricRequired]. - + @@ -184,7 +284,12 @@ When this metric is reported alongside a messaging receive span, the metric valu | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `messaging.receive.duration` | Histogram | `s` | Measures the duration of receive operation. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.client.consumed.messages` | Counter | `{message}` | Number of messages that were delivered to the application. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Records the number of messages pulled from the broker or number of messages dispatched to the application in push-based scenarios. +The metric SHOULD be reported once per message delivery. For example, if receiving and processing operations are both instrumented for a single message delivery, this counter is incremented when the message is received and not reported when it is processed. + @@ -192,22 +297,88 @@ When this metric is reported alongside a messaging receive span, the metric valu -### Metric: `messaging.receive.messages` - -This metric is [required][MetricRequired] for batch receive operations. It's [opt-in][MetricOptIn] when the messaging system does not support batch receive since the message count can be derived from the `messaging.receive.duration` histogram. - -_Note: The need to report `messaging.receive.messages` depends on the messaging system capabilities and not application scenarios or client library limitations._ - - + -| Name | Instrument Type | Unit (UCUM) | Description | Stability | -| -------- | --------------- | ----------- | -------------- | --------- | -| `messaging.receive.messages` | Counter | `{message}` | Measures the number of received messages. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `receive`; `peek`; `poll`; `consume` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.system`](/docs/attributes-registry/messaging.md) | string | The messaging system as identified by the client instrumentation. [1] | `activemq`; `aws_sqs`; `eventgrid` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) | string | The name of the consumer group with which a consumer is associated. [3] | `my-group`; `indexer` | `Conditionally Required` if applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [4] | `MyQueue`; `MyTopic` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | The name of the destination subscription from which a message is consumed. [6] | `subscription-a` | `Conditionally Required` if applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.template`](/docs/attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [7] | `/customers/{customerId}` | `Conditionally Required` if available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [9] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[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. + +**[2]:** 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. + +**[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. + +**[4]:** 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. + +**[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. + +**[8]:** 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. + + + +`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +`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 | +|---|---|---| +| `activemq` | Apache ActiveMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws_sqs` | Amazon Simple Queue Service (SQS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `eventgrid` | Azure Event Grid | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `eventhubs` | Azure Event Hubs | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp_pubsub` | Google Cloud Pub/Sub | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `jms` | Java Message Service | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `kafka` | Apache Kafka | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pulsar` | Apache Pulsar | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rabbitmq` | RabbitMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rocketmq` | Apache RocketMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `servicebus` | Azure Service Bus | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + @@ -217,10 +388,10 @@ _Note: The need to report `messaging.receive.messages` depends on the messaging ### Metric: `messaging.process.duration` -This metric is [required][MetricRequired] for operations that are not initiated by the application code (push-based deliver), and [recommended][MetricRecommended] for processing operations instrumented for pull-based scenarios. - When this metric is reported alongside a messaging process span, the metric value SHOULD be the same as the corresponding span duration. +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.33.0/specification/metrics/api.md#instrument-advice) 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 ]`. @@ -234,7 +405,11 @@ 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 | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `messaging.process.duration` | Histogram | `s` | Measures the duration of process operation. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.process.duration` | Histogram | `s` | Duration of processing operation. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** This metric MUST be reported for operations with `messaging.operation.type` that matches `process`. + @@ -242,22 +417,88 @@ 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: `messaging.process.messages` - -This metric is [required][MetricRequired] for batch process operations, and [recommended][MetricRecommended] for batch processing operations instrumented for pull-based scenarios. It's [opt-in][MetricOptIn] when the messaging system does not support batch processing since the message count can be derived from the `messaging.process.duration` histogram. - -_Note: The need to report `messaging.process.messages` depends on the messaging system capabilities and not application scenarios or client library limitations._ - - + -| Name | Instrument Type | Unit (UCUM) | Description | Stability | -| -------- | --------------- | ----------- | -------------- | --------- | -| `messaging.process.messages` | Counter | `{message}` | Measures the number of processed messages. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `process`; `consume`; `handle` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.system`](/docs/attributes-registry/messaging.md) | string | The messaging system as identified by the client instrumentation. [1] | `activemq`; `aws_sqs`; `eventgrid` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) | string | The name of the consumer group with which a consumer is associated. [3] | `my-group`; `indexer` | `Conditionally Required` if applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [4] | `MyQueue`; `MyTopic` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | The name of the destination subscription from which a message is consumed. [6] | `subscription-a` | `Conditionally Required` if applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.template`](/docs/attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [7] | `/customers/{customerId}` | `Conditionally Required` if available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [9] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[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. + +**[2]:** 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. + +**[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. + +**[4]:** 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. + +**[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. + +**[8]:** 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. + + + +`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +`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 | +|---|---|---| +| `activemq` | Apache ActiveMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws_sqs` | Amazon Simple Queue Service (SQS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `eventgrid` | Azure Event Grid | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `eventhubs` | Azure Event Hubs | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp_pubsub` | Google Cloud Pub/Sub | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `jms` | Java Message Service | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `kafka` | Apache Kafka | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pulsar` | Apache Pulsar | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rabbitmq` | RabbitMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rocketmq` | Apache RocketMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `servicebus` | Azure Service Bus | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + @@ -268,4 +509,3 @@ _Note: The need to report `messaging.process.messages` depends on the messaging [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 -[MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 3221b076da..0855774bcf 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -13,6 +13,8 @@ - [Intermediary](#intermediary) - [Destinations](#destinations) - [Message consumption](#message-consumption) + - [Consumer groups](#consumer-groups) + - [Subscriptions](#subscriptions) - [Conversations](#conversations) - [Temporary and anonymous destinations](#temporary-and-anonymous-destinations) - [Conventions](#conventions) @@ -25,13 +27,11 @@ - [Consumer spans](#consumer-spans) - [Messaging attributes](#messaging-attributes) - [Consumer attributes](#consumer-attributes) - - [Per-message attributes](#per-message-attributes) - - [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems) + - [Recording per-message attributes on batch operations](#recording-per-message-attributes-on-batch-operations) - [Examples](#examples) - [Topic with multiple consumers](#topic-with-multiple-consumers) - [Batch receiving](#batch-receiving) - [Batch publishing](#batch-publishing) -- [Semantic Conventions for specific messaging technologies](#semantic-conventions-for-specific-messaging-technologies) @@ -104,6 +104,23 @@ First, the lower-level receiving of a message at a consumer, and then the logica Often, the waiting for a message is not particularly interesting and hidden away in a framework that only invokes some handler function to process a message once one is received (in the same way that the listening on a TCP port for an incoming HTTP message is not particularly interesting). +#### Consumer groups + +Consumer groups provide a logical grouping for the message consumers. Messaging systems use them to +load balance message consumption within the group, broadcast messages to multiple types of the consumers, +manage offset for each group independently. +As a result, different groups of consumers can receive messages at a different pace +or using different settings. + +#### Subscriptions + +Subscriptions represent entities within messaging systems that allow multiple consumers +to receive messages from the topic following subscription-specific consumption behavior that includes +load balancing, durability, filtering, or other system-specific capabilities. + +Named subscriptions and consumers groups are semantically different mechanisms messaging systems use +for similar scenarios such as load-balancing or broadcasting. + ### Conversations In some messaging systems, a message can receive one or more reply messages that answers a particular other message that was sent earlier. All messages that are grouped together by such a reply-relationship are called a *conversation*. @@ -153,36 +170,32 @@ in such a way that it cannot be changed by intermediaries. ### Span name -The span name SHOULD be set to the message destination name and the name of the operation being performed (as captured in [`messaging.operation.name`](../attributes-registry/messaging.md)) in the following format: +Messaging spans SHOULD follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/trace/api.md#span). -``` - -``` + + +The **span name** SHOULD be `{messaging.operation.name} {destination}` (see below for the exact definition of the [`{destination}`](#destination-placeholder) placeholder). + -If the operation name is not specified by the messaging system, then the operation type as defined in [Operation types](#operation-types) SHOULD be used: +Semantic conventions for individual messaging systems MAY specify different span name format and then MUST document it in semantic conventions for specific messaging technologies. -``` - -``` +The `{destination}` SHOULD describe the entity that the operation is performed against +and SHOULD adhere to one of the following values, provided they are accessible: -The destination name SHOULD only be used for the span name if it is known to be of low cardinality (cf. [general span name guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/trace/api.md#span)). -This can be assumed if it is statically derived from application code or configuration. -Wherever possible, the real destination names after resolving logical or aliased names SHOULD be used. -If the destination name is dynamic, such as a [conversation ID](#conversations) or a value obtained from a `Reply-To` header, it SHOULD NOT be used for the span name. -In these cases, an artificial destination name that best expresses the destination, or a generic, static fallback like `"(anonymous)"` for [anonymous destinations](#temporary-and-anonymous-destinations) SHOULD be used instead. +1. `messaging.destination.template` SHOULD be used when it is available. +2. `messaging.destination.name` SHOULD be used when the destination is known to be neither [temporary nor anonymous](#temporary-and-anonymous-destinations). +3. `server.address:server.port` SHOULD be used only for operations not targeting any specific destination(s). -Examples: +If a corresponding `{destination}` value is not available for a specific operation, the instrumentation SHOULD omit the `{destination}`. -* `shop.orders publish` -* `shop.orders subscribe` -* `shop.orders settle` -* `print_jobs publish` -* `print_jobs nack` -* `topic with spaces process` -* `AuthenticationRequest-Conversations settle` -* `(anonymous) send` (`(anonymous)` being a stable identifier for an unnamed destination) +Examples: -Messaging system specific adaptions to span naming MUST be documented in [semantic conventions for specific messaging technologies](#semantic-conventions-for-specific-messaging-technologies). +* `publish shop.orders` +* `subscribe shop.orders` +* `ack shop.orders` +* `nack print_jobs` +* `process topic with spaces` +* `settle AuthenticationRequest-Conversations` ### Operation types @@ -193,20 +206,19 @@ The following operation types related to messages are defined for these semantic | `create` | A message is created or passed to a client library for publishing. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | | `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. | | `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | -| `process` | One or more messages are delivered to or processed by a consumer. | +| `process` | One or more messages are processed by a consumer. | | `settle` | One or more messages are settled. | ### Span kind -[Span kinds](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/trace/api.md#spankind) -SHOULD be set according to the following table, based on the operation type a span describes. +Span kind SHOULD be set according to the following table, based on the operation type a span describes. | Operation type | Span kind| |----------------|-------------| | `create` | `PRODUCER` | | `publish` | `PRODUCER` if the context of the "Publish" span is used as creation context. | | `receive` | `CONSUMER` | -| `process` | `CONSUMER` for push-based scenarios where no `receive` span exists. | +| `process` | `CONSUMER` for push-based scenarios where no "Receive" span exists. | For cases not covered by the table above, the span kind should be set according to the [generic specification about span kinds](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/trace/api.md#spankind), @@ -274,14 +286,13 @@ context of the message. Messaging attributes are organized into the following namespaces: -- `messaging.message`: Contains [per-message attributes](#per-message-attributes) that describe individual messages. Those attributes are relevant only for spans or links that represent a single message. +- `messaging.message`: Contains attributes that describe individual messages. - `messaging.destination`: Contains attributes that describe the logical entity messages are published to. See [Destinations](#destinations) for more details. - `messaging.destination_publish`: Contains attributes that describe the logical entity messages were originally published to. See [Destinations](#destinations) for more details. - `messaging.batch`: Contains attributes that describe batch operations. - `messaging.consumer`: Contains [consumer attributes](#consumer-attributes) that describe the application instance that consumes a message. See [consumer](#consumer) for more details. -Messaging system-specific attributes MUST be defined in the corresponding `messaging.{system}` namespace -as described in [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems). +Messaging system-specific attributes MUST be defined in the corresponding `messaging.{system}` namespace. @@ -292,31 +303,31 @@ as described in [Attributes specific to certain messaging systems](#attributes-s | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [1] | `publish`; `create`; `receive` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.system`](/docs/attributes-registry/messaging.md) | string | The messaging system as identified by the client instrumentation. [2] | `activemq`; `aws_sqs`; `eventgrid` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | `Conditionally Required` If and only if the messaging operation has failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`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. [4] | `0`; `1`; `2` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.system`](/docs/attributes-registry/messaging.md) | string | The messaging system as identified by the client instrumentation. [1] | `activemq`; `aws_sqs`; `eventgrid` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) | string | The name of the consumer group with which a consumer is associated. [5] | `my-group`; `indexer` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.anonymous`](/docs/attributes-registry/messaging.md) | boolean | A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name). | | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [7] | `MyQueue`; `MyTopic` | `Conditionally Required` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.destination.template`](/docs/attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [9] | `/customers/{customerId}` | `Conditionally Required` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.destination.temporary`](/docs/attributes-registry/messaging.md) | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | `Conditionally Required` [11] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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. [12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`messaging.client.id`](/docs/attributes-registry/messaging.md) | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | `Recommended` If a client id is available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | The name of the destination subscription from which a message is consumed. [9] | `subscription-a` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.template`](/docs/attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [10] | `/customers/{customerId}` | `Conditionally Required` [11] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.temporary`](/docs/attributes-registry/messaging.md) | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | `Conditionally Required` [12] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [13] | `publish`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. [14] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`messaging.client.id`](/docs/attributes-registry/messaging.md) | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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` When applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.message.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. [13] | `1439` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.message.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. [15] | `1439` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.conversation_id`](/docs/attributes-registry/messaging.md) | string | The conversation ID identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.message.envelope.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body and metadata in bytes. [14] | `2738` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.message.envelope.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body and metadata in bytes. [16] | `2738` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | `Recommended` [15] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the messaging intermediary node where the operation was performed. [16] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this messaging system. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the messaging intermediary node where the operation was performed. [17] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this messaging system. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port of the messaging intermediary node where the operation was performed. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [17] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - -**[1]:** If a custom value is used, it MUST be of low cardinality. +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [18] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[2]:** 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]:** 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. -**[3]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. +**[2]:** 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. @@ -336,9 +347,11 @@ 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. -**[4]:** 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]:** 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]:** 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. **[6]:** If value is `true`. When missing, the value is assumed to be `false`. @@ -347,30 +360,46 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi **[8]:** If span describes operation on a single message or if the value applies to all messages in the batch. -**[9]:** 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. +**[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. -**[10]:** If available. Instrumentations MUST NOT use `messaging.destination.name` as template unless low-cardinality of destination name is guaranteed. +**[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. -**[11]:** If value is `true`. When missing, the value is assumed to be `false`. +**[11]:** If available. Instrumentations MUST NOT use `messaging.destination.name` as template unless low-cardinality of destination name is guaranteed. -**[12]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. +**[12]:** If value is `true`. When missing, the value is assumed to be `false`. -**[13]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed +**[13]:** 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. + +**[15]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed body size should be used. -**[14]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed +**[16]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed size should be used. -**[15]:** If the operation is not sufficiently described by `messaging.operation.type`. - -**[16]:** Semantic conventions for individual messaging systems SHOULD document whether `network.peer.*` attributes are applicable. +**[17]:** 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. -**[17]:** 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. +**[18]:** 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): + +* [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) +* [`messaging.destination.name`](/docs/attributes-registry/messaging.md) +* [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) +* [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) +* [`messaging.destination.template`](/docs/attributes-registry/messaging.md) +* [`messaging.operation.name`](/docs/attributes-registry/messaging.md) +* [`messaging.operation.type`](/docs/attributes-registry/messaging.md) +* [`messaging.system`](/docs/attributes-registry/messaging.md) +* [`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 | @@ -383,7 +412,7 @@ If a messaging operation involved multiple network calls (for example retries), | Value | Description | Stability | |---|---|---| | `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `process` | One or more messages are delivered to or processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process` | One or more messages are processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `settle` | One or more messages are settled. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -440,30 +469,29 @@ the broker doesn't have such notion, the original destination name SHOULD unique +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`messaging.destination_publish.name`](/docs/attributes-registry/messaging.md) + -### Per-message attributes +### Recording per-message attributes on batch operations All messaging operations (`publish`, `receive`, `process`, or others not covered by this specification) can describe both single and/or batch of messages. -Attributes in the `messaging.message` or `messaging.{system}.message` namespace describe individual messages. For single-message operations they SHOULD be set on corresponding span. - -For batch operations, per-message attributes are usually different and cannot be set on the corresponding span. In such cases the attributes SHOULD be set on links. See [Batch receiving](#batch-receiving) for more information on correlation using links. - -Some messaging systems (e.g., Kafka, Azure EventGrid) allow publishing a single batch of messages to different topics. In such cases, the attributes in `messaging.destination` MAY be -set on links. Instrumentations MAY set destination attributes on the span if all messages in the batch share the same destination. +Attributes in the `messaging.message` or `messaging.{system}.message` namespace apply to individual messages and typically vary between messages within the same batch. -### Attributes specific to certain messaging systems +Some messaging systems such as Kafka or Azure Event Grid allow publishing a batch of messages to different topics in a single operation, resulting in +different `messaging.destination.name` or other destination attributes within a single messaging operation. -All attributes that are specific for a messaging system SHOULD be populated in `messaging.{system}` namespace. Attributes that describe a message, a destination, a consumer, or a batch of messages SHOULD be populated under the corresponding namespace: +If the attribute value is the same for all messages in the batch, the instrumentation SHOULD set such attribute on the span representing the batch operation. +If the attribute values vary, the instrumentation SHOULD set such attributes on links describing individual messages. -* `messaging.{system}.message.*`: Describes attributes for individual messages -* `messaging.{system}.destination.*`: Describes the destination a message (or a batch) are published to and received from respectively. The combination of attributes in these namespaces should uniquely identify the entity and include properties significant for this messaging system. For example, Kafka instrumentations should include partition identifier. -* `messaging.{system}.consumer.*`: Describes message consumer properties -* `messaging.{system}.batch.*`: Describes message batch properties +See [Batch receiving](#batch-receiving) for more information on correlation using links. ## Examples @@ -503,14 +531,15 @@ flowchart LR; | Field or Attribute | Span Publish A | Span Process A 1| Span Process A 2 | |-|-|-|-| -| Span name | `T publish` | `T process` | `T process` | +| Span name | `publish T` | `consume T` | `consume T` | | Parent | | | | -| Links | | `T publish` | `T publish` | +| Links | | `publish T` | `publish T` | | SpanKind | `PRODUCER` | `CONSUMER` | `CONSUMER` | | `server.address` | `"ms"` | `"ms"` | `"ms"` | | `server.port` | `1234` | `1234` | `1234` | | `messaging.system` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` | | `messaging.destination.name` | `"T"` | `"T"` | `"T"` | +| `messaging.operation.name` | `"publish"` | `"consume"` | `"consume"` | | `messaging.operation.type` | `"publish"` | `"process"` | `"process"` | | `messaging.message.id` | `"a"` | `"a"`| `"a"` | @@ -539,7 +568,7 @@ flowchart LR; | Field or Attribute | Span Publish A | Span Publish B | Span Receive A B | |-|-|-|-| -| Span name | `Q publish` | `Q publish` | `Q receive` | +| Span name | `send Q` | `send Q` | `poll Q` | | Parent | | | | | Links | | | Span Publish A, Span Publish B | | Link attributes | | | Span Publish A: `messaging.message.id`: `"a1"` | @@ -549,6 +578,7 @@ flowchart LR; | `server.port` | `1234` | `1234` | `1234` | | `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | | `messaging.destination.name` | `"Q"` | `"Q"` | `"Q"` | +| `messaging.operation.name` | `"send"` | `"send"` | `"poll"` | | `messaging.operation.type` | `"publish"` | `"publish"` | `"receive"` | | `messaging.message.id` | `"a1"` | `"a2"` | | | `messaging.batch.message_count` | | | 2 | @@ -586,7 +616,7 @@ flowchart LR; | Field or Attribute | Span Create A | Span Create B | Span Publish | Span Receive A | Span Receive B | |-|-|-|-|-|-| -| Span name | `Q create` | `Q create` | `Q publish` | `Q receive` | `Q receive` | +| Span name | `create Q` | `create Q` | `send Q` | `poll Q` | `poll Q` | | Parent | | | | | | | Links | | | | Span Create A | Span Create B | | SpanKind | `PRODUCER` | `PRODUCER` | `CLIENT` | `CONSUMER` | `CONSUMER` | @@ -594,16 +624,9 @@ flowchart LR; | `server.port` | `1234` | `1234` | `1234` | `1234` | `1234` | | `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | | `messaging.destination.name` | `"Q"` | `"Q"` | `"Q"` | `"Q"` | `"Q"` | +| `messaging.operation.name` | `"create"` | `"create"` | `"send"` | `"poll"` | `"poll"` | | `messaging.operation.type` | `"create"` | `"create"` | `"publish"` | `"receive"` | `"receive"` | | `messaging.message.id` | `"a1"` | `"a2"` | | `"a1"` | `"a2"` | | `messaging.batch.message_count` | | | 2 | | | -## Semantic Conventions for specific messaging technologies - -More specific Semantic Conventions are defined for the following messaging technologies: - -* [Kafka](kafka.md): Semantic Conventions for *Apache Kafka*. -* [RabbitMQ](rabbitmq.md): Semantic Conventions for *RabbitMQ*. -* [RocketMQ](rocketmq.md): Semantic Conventions for *Apache RocketMQ*. - [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md index 11c4a761ae..bd4a1ed73d 100644 --- a/docs/messaging/rabbitmq.md +++ b/docs/messaging/rabbitmq.md @@ -10,7 +10,7 @@ The Semantic Conventions for [RabbitMQ](https://www.rabbitmq.com/) extend and ov that describe common messaging operations attributes in addition to the Semantic Conventions described on this page. -`messaging.system` MUST be set to `"rabbitmq"`. +`messaging.system` MUST be set to `"rabbitmq"` and SHOULD be provided **at span creation time**. ## RabbitMQ attributes @@ -26,23 +26,21 @@ In RabbitMQ, the destination is defined by an *exchange* and a *routing key*. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [1] | `publish`; `create`; `receive` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [3] | `MyQueue`; `MyTopic` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | `Conditionally Required` If and only if the messaging operation has failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [2] | `MyQueue`; `MyTopic` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [4] | `publish`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rabbitmq.destination.routing_key`](/docs/attributes-registry/messaging.md) | string | RabbitMQ message routing key. | `myKey` | `Conditionally Required` If not empty. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rabbitmq.message.delivery_tag`](/docs/attributes-registry/messaging.md) | int | RabbitMQ message delivery tag | `123` | `Conditionally Required` When available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.message.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. [6] | `1439` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.conversation_id`](/docs/attributes-registry/messaging.md) | string | Message [correlation Id](https://www.rabbitmq.com/tutorials/tutorial-six-java#correlation-id) property. | `MyConversationId` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | `Recommended` [7] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. [8] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. [7] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [9] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [8] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** If a custom value is used, it MUST be of low cardinality. - -**[2]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. +**[1]:** 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. @@ -62,23 +60,32 @@ 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 +**[2]:** 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 span describes operation on a single message or if the value applies to all messages in the batch. +**[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. **[5]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. **[6]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed body size should be used. -**[7]:** If the operation is not sufficiently described by `messaging.operation.type`. +**[7]:** If an operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. + +**[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]:** If an operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. -**[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. +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): +* [`messaging.destination.name`](/docs/attributes-registry/messaging.md) +* [`messaging.operation.name`](/docs/attributes-registry/messaging.md) +* [`messaging.operation.type`](/docs/attributes-registry/messaging.md) +* [`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. @@ -92,7 +99,7 @@ body size should be used. | Value | Description | Stability | |---|---|---| | `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `process` | One or more messages are delivered to or processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process` | One or more messages are processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `settle` | One or more messages are settled. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md index 0c57e3f5c3..a602244433 100644 --- a/docs/messaging/rocketmq.md +++ b/docs/messaging/rocketmq.md @@ -10,7 +10,7 @@ The Semantic Conventions for [Apache RocketMQ](https://rocketmq.apache.org/) ext that describe common messaging operations attributes in addition to the Semantic Conventions described on this page. -`messaging.system` MUST be set to `"rocketmq"`. +`messaging.system` MUST be set to `"rocketmq"` and SHOULD be provided **at span creation time**. ## Apache RocketMQ attributes @@ -25,12 +25,13 @@ Specific attributes for Apache RocketMQ are defined below. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [1] | `publish`; `create`; `receive` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.rocketmq.client_group`](/docs/attributes-registry/messaging.md) | string | Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. | `myConsumerGroup` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) | string | RocketMQ [consumer group name](https://rocketmq.apache.org/docs/domainModel/07consumergroup). | `my-group`; `indexer` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rocketmq.namespace`](/docs/attributes-registry/messaging.md) | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [5] | `MyQueue`; `MyTopic` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | `Conditionally Required` If and only if the messaging operation has failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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. [2] | `0`; `1`; `2` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [4] | `MyQueue`; `MyTopic` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [6] | `publish`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rocketmq.message.delay_time_level`](/docs/attributes-registry/messaging.md) | int | The delay time level for delay message, which determines the message delay time. | `3` | `Conditionally Required` [7] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rocketmq.message.delivery_timestamp`](/docs/attributes-registry/messaging.md) | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | `Conditionally Required` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rocketmq.message.group`](/docs/attributes-registry/messaging.md) | string | It is essential for FIFO message. Messages that belong to the same message group are always processed one by one within the same consumer group. | `myMessageGroup` | `Conditionally Required` If the message type is FIFO. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -38,16 +39,13 @@ Specific attributes for Apache RocketMQ are defined below. | [`messaging.client.id`](/docs/attributes-registry/messaging.md) | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. [10] | `1439` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | `Recommended` [11] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rocketmq.consumption_model`](/docs/attributes-registry/messaging.md) | string | Model of message consumption. This only applies to consumer spans. | `clustering`; `broadcasting` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rocketmq.message.keys`](/docs/attributes-registry/messaging.md) | string[] | Key(s) of message, another way to mark message besides message id. | `["keyA", "keyB"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rocketmq.message.tag`](/docs/attributes-registry/messaging.md) | string | The secondary classifier of message besides topic. | `tagA` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rocketmq.message.type`](/docs/attributes-registry/messaging.md) | string | Type of message. | `normal`; `fifo`; `delay` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [12] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [11] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** If a custom value is used, it MUST be of low cardinality. - -**[2]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. +**[1]:** 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. @@ -67,14 +65,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]:** 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]:** 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. +**[3]:** 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 +**[4]:** 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. +**[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. **[7]:** If the message type is delay and delivery timestamp is not specified. @@ -85,11 +85,19 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi **[10]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed body size should be used. -**[11]:** If the operation is not sufficiently described by `messaging.operation.type`. +**[11]:** 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. + -**[12]:** 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): +* [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) +* [`messaging.destination.name`](/docs/attributes-registry/messaging.md) +* [`messaging.operation.name`](/docs/attributes-registry/messaging.md) +* [`messaging.operation.type`](/docs/attributes-registry/messaging.md) +* [`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. @@ -103,7 +111,7 @@ body size should be used. | Value | Description | Stability | |---|---|---| | `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `process` | One or more messages are delivered to or processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process` | One or more messages are processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `settle` | One or more messages are settled. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/resource/process.md b/docs/resource/process.md index a081022d6f..ff17dfcfbf 100644 --- a/docs/resource/process.md +++ b/docs/resource/process.md @@ -91,7 +91,7 @@ On Windows and other systems where the native format of process commands is a si | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`process.runtime.description`](/docs/attributes-registry/process.md) | string | An additional description about the runtime of the process, for example a specific vendor customization of the runtime environment. | `Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`process.runtime.name`](/docs/attributes-registry/process.md) | string | The name of the runtime of this process. For compiled native binaries, this SHOULD be the name of the compiler. | `OpenJDK Runtime Environment` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.runtime.name`](/docs/attributes-registry/process.md) | string | The name of the runtime of this process. | `OpenJDK Runtime Environment` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`process.runtime.version`](/docs/attributes-registry/process.md) | string | The version of the runtime of this process, as returned by the runtime without modification. | `14.0.2` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/runtime/README.md b/docs/runtime/README.md index bcabd1d7b6..7f17940f36 100644 --- a/docs/runtime/README.md +++ b/docs/runtime/README.md @@ -47,8 +47,10 @@ Also consider the [OS process metrics](/docs/system/process-metrics.md) semantic conventions when instrumenting runtime environments. -- [JVM](jvm-metrics.md) - [Go](go-metrics.md) +- [JVM](jvm-metrics.md) +- [Node.js](nodejs-metrics.md) +- [V8 JS Engine](v8js-metrics.md) ### Attributes diff --git a/docs/runtime/nodejs-metrics.md b/docs/runtime/nodejs-metrics.md new file mode 100644 index 0000000000..60fcd283af --- /dev/null +++ b/docs/runtime/nodejs-metrics.md @@ -0,0 +1,343 @@ + + +# Semantic Conventions for Node.js Runtime Metrics + +**Status**: [Experimental][DocumentStatus] + +This document describes semantic conventions for Node.js Runtime metrics in OpenTelemetry. + + + + + +- [Experimental](#experimental) + - [Metric: `nodejs.eventloop.delay.min`](#metric-nodejseventloopdelaymin) + - [Metric: `nodejs.eventloop.delay.max`](#metric-nodejseventloopdelaymax) + - [Metric: `nodejs.eventloop.delay.mean`](#metric-nodejseventloopdelaymean) + - [Metric: `nodejs.eventloop.delay.stddev`](#metric-nodejseventloopdelaystddev) + - [Metric: `nodejs.eventloop.delay.p50`](#metric-nodejseventloopdelayp50) + - [Metric: `nodejs.eventloop.delay.p90`](#metric-nodejseventloopdelayp90) + - [Metric: `nodejs.eventloop.delay.p99`](#metric-nodejseventloopdelayp99) + - [Metric: `nodejs.eventloop.utilization`](#metric-nodejseventlooputilization) + + + +## Experimental + +**Status**: [Experimental][DocumentStatus] + +**Description:** Experimental Node.js Runtime metrics captured under `nodejs`. + +Note: The metrics for eventloop delay are split into separated values instead of a single histogram, because node runtime +only returns single values through [`perf_hooks.monitorEventLoopDelay([options])`][Eventloop] and not the entire +histogram, so it's not possible to convert it to an OpenTelemetry histogram. + +### Metric: `nodejs.eventloop.delay.min` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.min` | Gauge | `s` | Event loop minimum delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.min` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.max` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.max` | Gauge | `s` | Event loop maximum delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.max` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.mean` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.mean` | Gauge | `s` | Event loop mean delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.mean` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.stddev` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.stddev` | Gauge | `s` | Event loop standard deviation delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.stddev` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.p50` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.p50` | Gauge | `s` | Event loop 50 percentile delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.percentile(50)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.p90` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.p90` | Gauge | `s` | Event loop 90 percentile delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.percentile(90)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.p99` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.p99` | Gauge | `s` | Event loop 99 percentile delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.percentile(99)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.utilization` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.utilization` | Gauge | `1` | Event loop utilization. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** The value range is [0.0,1.0] and can be retrieved from value [`performance.eventLoopUtilization([utilization1[, utilization2]])`](https://nodejs.org/api/perf_hooks.html#performanceeventlooputilizationutilization1-utilization2) + + + + + + + + + + + + + + + + + + + + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.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 new file mode 100644 index 0000000000..d8b4e07a65 --- /dev/null +++ b/docs/runtime/v8js-metrics.md @@ -0,0 +1,315 @@ + + +# Semantic Conventions for V8 JS Engine Runtime Metrics + +**Status**: [Experimental][DocumentStatus] + +This document describes semantic conventions for V8 JS Engine Runtime metrics in OpenTelemetry. This engine is used in some javascript runtime such as Node.js and Deno. + + + + + +- [Experimental](#experimental) + - [Metric: `v8js.gc.duration`](#metric-v8jsgcduration) + - [Metric: `v8js.memory.heap.limit`](#metric-v8jsmemoryheaplimit) + - [Metric: `v8js.memory.heap.used`](#metric-v8jsmemoryheapused) + - [Metric: `v8js.heap.space.available_size`](#metric-v8jsheapspaceavailable_size) + - [Metric: `v8js.heap.space.physical_size`](#metric-v8jsheapspacephysical_size) + + + +## Experimental + +**Status**: [Experimental][DocumentStatus] + +**Description:** Experimental V8 JS Engine Runtime metrics captured under `v8js`. + +### Metric: `v8js.gc.duration` + +This metric is [recommended][MetricRecommended]. + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/metrics/api.md#instrument-advisory-parameters) +of `[ 0.01, 0.1, 1, 10 ]`. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `v8js.gc.duration` | Histogram | `s` | Garbage collection duration. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** The values can be retrieve from [`perf_hooks.PerformanceObserver(...).observe({ entryTypes: ['gc'] })`](https://nodejs.org/api/perf_hooks.html#performanceobserverobserveoptions) + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`v8js.gc.type`](/docs/attributes-registry/v8js.md) | string | The type of garbage collection. | `major`; `minor`; `incremental` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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 | +|---|---|---| +| `incremental` | Incremental (Incremental Marking). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `major` | Major (Mark Sweep Compact). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `minor` | Minor (Scavenge). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `weakcb` | Weak Callbacks (Process Weak Callbacks). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `v8js.memory.heap.limit` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `v8js.memory.heap.limit` | UpDownCounter | `By` | Total heap memory size pre-allocated. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** The value can be retrieved from value `space_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** 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 | +|---|---|---| +| `code_space` | Code memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `v8js.memory.heap.used` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `v8js.memory.heap.used` | UpDownCounter | `By` | Heap Memory size allocated. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** The value can be retrieved from value `space_used_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** 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 | +|---|---|---| +| `code_space` | Code memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `v8js.heap.space.available_size` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `v8js.heap.space.available_size` | UpDownCounter | `By` | Heap space available size. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `space_available_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** 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 | +|---|---|---| +| `code_space` | Code memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `v8js.heap.space.physical_size` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `v8js.heap.space.physical_size` | UpDownCounter | `By` | Committed size of a heap space. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `physical_space_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** 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 | +|---|---|---| +| `code_space` | Code memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/docs/system/container-metrics.md b/docs/system/container-metrics.md index 5449a117d0..b0fb198f21 100644 --- a/docs/system/container-metrics.md +++ b/docs/system/container-metrics.md @@ -42,15 +42,24 @@ This metric is [opt-in][MetricOptIn]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`container.cpu.state`](/docs/attributes-registry/container.md) | string | The CPU state for this data point. A container SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `user`; `kernel` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`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. +**[1]:** Following states SHOULD be used: `user`, `system`, `kernel` + + + +`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 | |---|---|---| -| `kernel` | When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `system` | When CPU is used by the system (host OS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `user` | When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `kernel` | kernel | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index 5b40717462..892382e40f 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -75,15 +75,24 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`process.cpu.state`](/docs/attributes-registry/process.md) | string | A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `system`; `user`; `wait` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`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. +**[1]:** 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 | |---|---|---| +| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `kernel` | kernel | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `wait` | wait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -122,15 +131,24 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`process.cpu.state`](/docs/attributes-registry/process.md) | string | A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `system`; `user`; `wait` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Following states SHOULD be used: `user`, `system`, `wait` + + -`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. +`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 | |---|---|---| +| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `kernel` | kernel | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `wait` | wait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 70a9c543af..cd01009e28 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -104,16 +104,21 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`system.cpu.logical_number`](/docs/attributes-registry/system.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`system.cpu.state`](/docs/attributes-registry/system.md) | string | The CPU state for this data point. A system's CPU SHOULD be characterized *either* by data points with no `state` labels, *or only* data points with `state` labels. | `idle`; `interrupt` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`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. +**[1]:** 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 | |---|---|---| | `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `kernel` | kernel | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -156,16 +161,21 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`system.cpu.logical_number`](/docs/attributes-registry/system.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`system.cpu.state`](/docs/attributes-registry/system.md) | string | The CPU state for this data point. A system's CPU SHOULD be characterized *either* by data points with no `state` labels, *or only* data points with `state` labels. | `idle`; `interrupt` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`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. +**[1]:** 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 | |---|---|---| | `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `kernel` | kernel | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/messaging-common.yaml b/model/messaging-common.yaml index 403eeb4535..ab020e5fe6 100644 --- a/model/messaging-common.yaml +++ b/model/messaging-common.yaml @@ -15,3 +15,5 @@ groups: requirement_level: conditionally_required: If available. - ref: server.port + - ref: messaging.operation.name + requirement_level: required diff --git a/model/metrics/container.yaml b/model/metrics/container.yaml index f0e15ed596..94adad2921 100644 --- a/model/metrics/container.yaml +++ b/model/metrics/container.yaml @@ -10,8 +10,9 @@ groups: instrument: counter unit: "s" attributes: - - ref: container.cpu.state - brief: "The CPU state for this data point. A container SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels." + - ref: cpu.mode + brief: "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." + note: "Following states SHOULD be used: `user`, `system`, `kernel`" requirement_level: opt_in # container.memory.* metrics and attribute group diff --git a/model/metrics/database-metrics.yaml b/model/metrics/database-metrics.yaml index eef11ec5d4..45a92a12fc 100644 --- a/model/metrics/database-metrics.yaml +++ b/model/metrics/database-metrics.yaml @@ -41,9 +41,9 @@ groups: instrument: updowncounter unit: "{connection}" attributes: - - ref: db.client.connections.state + - ref: db.client.connection.state requirement_level: required - - ref: db.client.connections.pool.name + - ref: db.client.connection.pool.name requirement_level: required - id: metric.db.client.connection.idle.max @@ -54,7 +54,7 @@ groups: instrument: updowncounter unit: "{connection}" attributes: - - ref: db.client.connections.pool.name + - ref: db.client.connection.pool.name requirement_level: required - id: metric.db.client.connection.idle.min @@ -65,7 +65,7 @@ groups: instrument: updowncounter unit: "{connection}" attributes: - - ref: db.client.connections.pool.name + - ref: db.client.connection.pool.name requirement_level: required - id: metric.db.client.connection.max @@ -76,7 +76,7 @@ groups: instrument: updowncounter unit: "{connection}" attributes: - - ref: db.client.connections.pool.name + - ref: db.client.connection.pool.name requirement_level: required - id: metric.db.client.connection.pending_requests @@ -87,7 +87,7 @@ groups: instrument: updowncounter unit: "{request}" attributes: - - ref: db.client.connections.pool.name + - ref: db.client.connection.pool.name requirement_level: required - id: metric.db.client.connection.timeouts @@ -98,7 +98,7 @@ groups: instrument: counter unit: "{timeout}" attributes: - - ref: db.client.connections.pool.name + - ref: db.client.connection.pool.name requirement_level: required - id: metric.db.client.connection.create_time @@ -109,7 +109,7 @@ groups: instrument: histogram unit: "s" attributes: - - ref: db.client.connections.pool.name + - ref: db.client.connection.pool.name requirement_level: required - id: metric.db.client.connection.wait_time @@ -120,7 +120,7 @@ groups: instrument: histogram unit: "s" attributes: - - ref: db.client.connections.pool.name + - ref: db.client.connection.pool.name requirement_level: required - id: metric.db.client.connection.use_time @@ -131,5 +131,5 @@ groups: instrument: histogram unit: "s" attributes: - - ref: db.client.connections.pool.name + - ref: db.client.connection.pool.name requirement_level: required diff --git a/model/metrics/deprecated/messaging-metrics.yaml b/model/metrics/deprecated/messaging-metrics.yaml new file mode 100644 index 0000000000..c0746d70ab --- /dev/null +++ b/model/metrics/deprecated/messaging-metrics.yaml @@ -0,0 +1,50 @@ +groups: + - id: metric.messaging.publish.duration + type: metric + metric_name: messaging.publish.duration + brief: "Deprecated. Use `messaging.client.operation.duration` instead." + deprecated: "Replaced by `messaging.client.operation.duration`." + stability: experimental + instrument: histogram + unit: "s" + extends: attributes.messaging.common.minimal + + - id: metric.messaging.receive.duration + type: metric + metric_name: messaging.receive.duration + brief: "Deprecated. Use `messaging.client.operation.duration` instead." + deprecated: "Replaced by `messaging.client.operation.duration`." + stability: experimental + instrument: histogram + unit: "s" + extends: attributes.messaging.common.minimal + + - id: metric.messaging.process.messages + type: metric + metric_name: messaging.process.messages + brief: "Deprecated. Use `messaging.client.consumed.messages` instead." + deprecated: "Replaced by `messaging.client.consumed.messages`." + stability: experimental + instrument: counter + unit: "{message}" + extends: attributes.messaging.common.minimal + + - id: metric.messaging.publish.messages + type: metric + metric_name: messaging.publish.messages + brief: "Deprecated. Use `messaging.client.produced.messages` instead." + deprecated: "Replaced by `messaging.client.produced.messages`." + stability: experimental + instrument: counter + unit: "{message}" + extends: attributes.messaging.common.minimal + + - id: metric.messaging.receive.messages + type: metric + metric_name: messaging.receive.messages + brief: "Deprecated. Use `messaging.client.consumed.messages` instead." + deprecated: "Replaced by `messaging.client.consumed.messages`." + stability: experimental + instrument: counter + unit: "{message}" + extends: attributes.messaging.common.minimal diff --git a/model/metrics/gen-ai.yaml b/model/metrics/gen-ai.yaml index 8398e8f0c6..7c9979cf21 100644 --- a/model/metrics/gen-ai.yaml +++ b/model/metrics/gen-ai.yaml @@ -16,6 +16,18 @@ groups: requirement_level: required - ref: gen_ai.operation.name requirement_level: required + - id: metric_attributes.gen_ai.server + type: attribute_group + brief: 'This group describes GenAI server metrics attributes' + extends: metric_attributes.gen_ai + attributes: + - ref: error.type + requirement_level: + conditionally_required: "if the operation ended in an error" + note: | + 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. - id: metric.gen_ai.client.token.usage type: metric metric_name: gen_ai.client.token.usage @@ -43,3 +55,27 @@ groups: 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. + - id: metric.gen_ai.server.request.duration + type: metric + metric_name: gen_ai.server.request.duration + brief: 'Generative AI server request duration such as time-to-last byte or last output token' + instrument: histogram + unit: "s" + stability: experimental + extends: metric_attributes.gen_ai.server + - id: metric.gen_ai.server.time_per_output_token + type: metric + metric_name: gen_ai.server.time_per_output_token + brief: 'Time per output token generated after the first token for successful responses' + instrument: histogram + unit: "s" + stability: experimental + extends: metric_attributes.gen_ai + - id: metric.gen_ai.server.time_to_first_token + type: metric + metric_name: gen_ai.server.time_to_first_token + brief: 'Time to generate first token for successful responses' + instrument: histogram + unit: "s" + stability: experimental + extends: metric_attributes.gen_ai diff --git a/model/metrics/messaging-metrics.yaml b/model/metrics/messaging-metrics.yaml new file mode 100644 index 0000000000..5dd4891fb9 --- /dev/null +++ b/model/metrics/messaging-metrics.yaml @@ -0,0 +1,94 @@ +groups: + - id: metric.messaging.attributes + type: attribute_group + stability: experimental + brief: "Common messaging metrics attributes." + extends: attributes.messaging.common.minimal + attributes: + - ref: messaging.system + requirement_level: required + - ref: messaging.destination.partition.id + - ref: messaging.destination.name + requirement_level: + conditionally_required: if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. + - ref: messaging.destination.template + requirement_level: + conditionally_required: if available. + + - id: metric.messaging.consumer.attributes + type: attribute_group + stability: experimental + brief: "Messaging consumer metrics attributes." + extends: metric.messaging.attributes + attributes: + - ref: messaging.consumer.group.name + requirement_level: + conditionally_required: if applicable. + - ref: messaging.destination.subscription.name + requirement_level: + conditionally_required: if applicable. + + # durations + - id: metric.messaging.client.operation.duration + type: metric + metric_name: messaging.client.operation.duration + brief: "Duration of messaging operation initiated by a producer or consumer client." + note: > + This metric SHOULD NOT be used to report processing duration - processing duration is reported in `messaging.process.duration` metric. + stability: experimental + instrument: histogram + unit: "s" + extends: metric.messaging.consumer.attributes + attributes: + - ref: messaging.operation.type + requirement_level: + conditionally_required: If applicable. + - ref: messaging.operation.name + examples: ["send", "receive", "ack"] + + - id: metric.messaging.process.duration + type: metric + metric_name: messaging.process.duration + brief: "Duration of processing operation." + note: > + This metric MUST be reported for operations with `messaging.operation.type` that matches `process`. + stability: experimental + instrument: histogram + unit: "s" + extends: metric.messaging.consumer.attributes + attributes: + - ref: messaging.operation.name + examples: ["process", "consume", "handle"] + + # counters + - id: metric.messaging.client.published.messages + type: metric + metric_name: messaging.client.published.messages + brief: "Number of messages producer attempted to publish to the broker." + note: > + This metric MUST NOT count messages that were created haven't yet been attempted to be published. + stability: experimental + instrument: counter + unit: "{message}" + extends: metric.messaging.attributes + attributes: + - ref: messaging.operation.name + examples: ["send", "schedule", "enqueue"] + + - id: metric.messaging.client.consumed.messages + type: metric + metric_name: messaging.client.consumed.messages + brief: "Number of messages that were delivered to the application." + note: > + Records the number of messages pulled from the broker or number of messages dispatched to the application in push-based scenarios. + + The metric SHOULD be reported once per message delivery. For example, if receiving and + processing operations are both instrumented for a single message delivery, this counter + is incremented when the message is received and not reported when it is processed. + stability: experimental + instrument: counter + unit: "{message}" + extends: metric.messaging.consumer.attributes + attributes: + - ref: messaging.operation.name + examples: ["receive", "peek", "poll", "consume"] diff --git a/model/metrics/messaging.yaml b/model/metrics/messaging.yaml deleted file mode 100644 index 43c76a9eb8..0000000000 --- a/model/metrics/messaging.yaml +++ /dev/null @@ -1,72 +0,0 @@ -groups: - - id: metric.messaging.attributes - type: attribute_group - stability: experimental - brief: "Common messaging metrics attributes." - extends: attributes.messaging.common.minimal - attributes: - - ref: messaging.system - requirement_level: required - - ref: messaging.destination.partition.id - - ref: messaging.destination.name - requirement_level: - conditionally_required: if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. - - ref: messaging.destination.template - requirement_level: - conditionally_required: if available. - - # durations - - id: metric.messaging.publish.duration - type: metric - metric_name: messaging.publish.duration - brief: "Measures the duration of publish operation." - stability: experimental - instrument: histogram - unit: "s" - extends: metric.messaging.attributes - - - id: metric.messaging.receive.duration - type: metric - metric_name: messaging.receive.duration - brief: "Measures the duration of receive operation." - stability: experimental - instrument: histogram - unit: "s" - extends: metric.messaging.attributes - - - id: metric.messaging.process.duration - type: metric - metric_name: messaging.process.duration - brief: "Measures the duration of process operation." - stability: experimental - instrument: histogram - unit: "s" - extends: metric.messaging.attributes - - # counters - - id: metric.messaging.publish.messages - type: metric - metric_name: messaging.publish.messages - brief: "Measures the number of published messages." - stability: experimental - instrument: counter - unit: "{message}" - extends: metric.messaging.attributes - - - id: metric.messaging.receive.messages - type: metric - metric_name: messaging.receive.messages - brief: "Measures the number of received messages." - stability: experimental - instrument: counter - unit: "{message}" - extends: metric.messaging.attributes - - - id: metric.messaging.process.messages - type: metric - metric_name: messaging.process.messages - brief: "Measures the number of processed messages." - stability: experimental - instrument: counter - unit: "{message}" - extends: metric.messaging.attributes diff --git a/model/metrics/nodejs-metrics.yaml b/model/metrics/nodejs-metrics.yaml new file mode 100644 index 0000000000..9def4fa143 --- /dev/null +++ b/model/metrics/nodejs-metrics.yaml @@ -0,0 +1,81 @@ +groups: + - id: metric.nodejs.eventloop.delay.min + type: metric + metric_name: nodejs.eventloop.delay.min + brief: "Event loop minimum delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.min` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.max + type: metric + metric_name: nodejs.eventloop.delay.max + brief: "Event loop maximum delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.max` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.mean + type: metric + metric_name: nodejs.eventloop.delay.mean + brief: "Event loop mean delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.mean` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.stddev + type: metric + metric_name: nodejs.eventloop.delay.stddev + brief: "Event loop standard deviation delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.stddev` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.pfifty + type: metric + metric_name: nodejs.eventloop.delay.p50 + brief: "Event loop 50 percentile delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.percentile(50)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.pninety + type: metric + metric_name: nodejs.eventloop.delay.p90 + brief: "Event loop 90 percentile delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.percentile(90)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.pninety_nine + type: metric + metric_name: nodejs.eventloop.delay.p99 + brief: "Event loop 99 percentile delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.percentile(99)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.utilization + type: metric + metric_name: nodejs.eventloop.utilization + brief: "Event loop utilization." + instrument: gauge + unit: "1" + stability: experimental + note: > + The value range is [0.0,1.0] and can be retrieved from value + [`performance.eventLoopUtilization([utilization1[, utilization2]])`](https://nodejs.org/api/perf_hooks.html#performanceeventlooputilizationutilization1-utilization2) diff --git a/model/metrics/process-metrics.yaml b/model/metrics/process-metrics.yaml index 3941cdc56d..86d224d543 100644 --- a/model/metrics/process-metrics.yaml +++ b/model/metrics/process-metrics.yaml @@ -7,10 +7,11 @@ groups: instrument: counter unit: "s" attributes: - - ref: process.cpu.state + - ref: cpu.mode brief: > - A process SHOULD be characterized _either_ by data points with no `state` - labels, _or only_ data points with `state` labels. + A process SHOULD be characterized _either_ by data points with no `mode` + labels, _or only_ data points with `mode` labels. + note: "Following states SHOULD be used: `user`, `system`, `wait`" - id: metric.process.cpu.utilization type: metric @@ -22,10 +23,11 @@ groups: instrument: gauge unit: "1" attributes: - - ref: process.cpu.state + - ref: cpu.mode brief: > - A process SHOULD be characterized _either_ by data points with no `state` - labels, _or only_ data points with `state` labels. + A process SHOULD be characterized _either_ by data points with no `mode` + labels, _or only_ data points with `mode` labels. + note: "Following states SHOULD be used: `user`, `system`, `wait`" - id: metric.process.memory.usage type: metric diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml index 1b7a2cf28e..25e2d06665 100644 --- a/model/metrics/system-metrics.yaml +++ b/model/metrics/system-metrics.yaml @@ -8,8 +8,9 @@ groups: instrument: counter unit: "s" attributes: - - ref: system.cpu.state - brief: "The CPU state for this data point. A system's CPU SHOULD be characterized *either* by data points with no `state` labels, *or only* data points with `state` labels." + - ref: cpu.mode + brief: "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." + note: "Following states SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`" - ref: system.cpu.logical_number - id: metric.system.cpu.utilization @@ -20,8 +21,9 @@ groups: instrument: gauge unit: "1" attributes: - - ref: system.cpu.state - brief: "The CPU state for this data point. A system's CPU SHOULD be characterized *either* by data points with no `state` labels, *or only* data points with `state` labels." + - ref: cpu.mode + brief: "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." + note: "Following modes SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`" - ref: system.cpu.logical_number - id: metric.system.cpu.frequency diff --git a/model/metrics/v8js-metrics.yaml b/model/metrics/v8js-metrics.yaml new file mode 100644 index 0000000000..be0a43b09a --- /dev/null +++ b/model/metrics/v8js-metrics.yaml @@ -0,0 +1,69 @@ +groups: + - id: metric.veightjs.gc.duration + type: metric + metric_name: v8js.gc.duration + brief: "Garbage collection duration." + instrument: histogram + unit: "s" + stability: experimental + prefix: v8js.gc + attributes: + - ref: v8js.gc.type + requirement_level: required + note: > + The values can be retrieve from [`perf_hooks.PerformanceObserver(...).observe({ entryTypes: ['gc'] })`](https://nodejs.org/api/perf_hooks.html#performanceobserverobserveoptions) + + - id: metric.veightjs.memory.heap.limit + type: metric + metric_name: v8js.memory.heap.limit + brief: "Total heap memory size pre-allocated." + instrument: updowncounter + unit: "By" + stability: experimental + attributes: + - ref: v8js.heap.space.name + requirement_level: required + note: > + The value can be retrieved from value `space_size` of + [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + - id: metric.veightjs.memory.heap.used + type: metric + metric_name: v8js.memory.heap.used + brief: "Heap Memory size allocated." + instrument: updowncounter + unit: "By" + stability: experimental + attributes: + - ref: v8js.heap.space.name + requirement_level: required + note: > + The value can be retrieved from value `space_used_size` of + [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + - id: metric.veightjs.heap.space.available_size + type: metric + metric_name: v8js.heap.space.available_size + brief: "Heap space available size." + instrument: updowncounter + unit: "By" + stability: experimental + attributes: + - ref: v8js.heap.space.name + requirement_level: required + note: > + Value can be retrieved from value `space_available_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + - id: metric.veightjs.heap.space.physical_size + type: metric + metric_name: v8js.heap.space.physical_size + brief: "Committed size of a heap space." + instrument: updowncounter + unit: "By" + stability: experimental + prefix: v8js.heap.space.physical_size + attributes: + - ref: v8js.heap.space.name + requirement_level: required + note: > + Value can be retrieved from value `physical_space_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) diff --git a/model/registry/container.yaml b/model/registry/container.yaml index b2ff38239f..60348628b4 100644 --- a/model/registry/container.yaml +++ b/model/registry/container.yaml @@ -95,22 +95,3 @@ groups: brief: > Container labels, `` being the label name, the value being the label value. examples: [ 'container.label.app=nginx' ] - - id: cpu.state - brief: "The CPU state for this data point." - type: - allow_custom_values: true - members: - - id: user - value: 'user' - brief: "When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows)." - stability: experimental - - id: system - value: 'system' - brief: "When CPU is used by the system (host OS)" - stability: experimental - - id: kernel - value: 'kernel' - brief: "When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows)." - stability: experimental - stability: experimental - examples: ["user", "kernel"] diff --git a/model/registry/cpu.yaml b/model/registry/cpu.yaml new file mode 100644 index 0000000000..43fb145a38 --- /dev/null +++ b/model/registry/cpu.yaml @@ -0,0 +1,38 @@ +groups: + - id: registry.cpu + prefix: cpu + type: attribute_group + brief: Attributes specific to a cpu instance. + attributes: + - id: mode + brief: "The mode of the CPU" + type: + allow_custom_values: true + # TODO: Fix how enum members are used in semantic conventions after https://github.com/open-telemetry/build-tools/issues/192 is merged + members: + - id: user + value: 'user' + stability: experimental + - id: system + value: 'system' + stability: experimental + - id: nice + value: 'nice' + stability: experimental + - id: idle + value: 'idle' + stability: experimental + - id: iowait + value: 'iowait' + stability: experimental + - id: interrupt + value: 'interrupt' + stability: experimental + - id: steal + value: 'steal' + stability: experimental + - id: kernel + value: 'kernel' + stability: experimental + stability: experimental + examples: [ "user", "system" ] diff --git a/model/registry/db.yaml b/model/registry/db.yaml index 56fe3294c1..c94ac32e0f 100644 --- a/model/registry/db.yaml +++ b/model/registry/db.yaml @@ -54,16 +54,22 @@ groups: brief: > The database query being executed. note: > + 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. examples: ['SELECT * FROM wuser_table where username = ?', 'SET mykey "WuValue"'] - id: query.parameter type: template[string] stability: experimental brief: > - The query parameters used in `db.query.text`, with `` being the parameter name, - and the attribute value being the parameter value. + A query parameter used in `db.query.text`, with `` being the parameter name, + and the attribute value being a string representation of the parameter value. note: > Query parameters should only be captured when `db.query.text` is parameterized with placeholders. @@ -97,7 +103,12 @@ groups: stability: experimental - id: cache value: 'cache' - brief: 'InterSystems Caché' + deprecated: "Replaced by `intersystems_cache`." + brief: "Deprecated, use `intersystems_cache` instead." + stability: experimental + - id: intersystems_cache + value: 'intersystems_cache' + brief: "InterSystems Caché" stability: experimental - id: cassandra value: 'cassandra' @@ -109,7 +120,8 @@ groups: stability: experimental - id: cloudscape value: 'cloudscape' - brief: 'Cloudscape' + deprecated: "Replaced by `other_sql`." + brief: "Deprecated, use `other_sql` instead." stability: experimental - id: cockroachdb value: 'cockroachdb' @@ -117,7 +129,8 @@ groups: stability: experimental - id: coldfusion value: 'coldfusion' - brief: 'ColdFusion IMQ' + deprecated: "Removed." + brief: "Deprecated, no replacement at this time." stability: experimental - id: cosmosdb value: 'cosmosdb' @@ -161,7 +174,8 @@ groups: stability: experimental - id: firstsql value: 'firstsql' - brief: 'FirstSQL' + deprecated: "Replaced by `other_sql`." + brief: "Deprecated, use `other_sql` instead." stability: experimental - id: geode value: 'geode' @@ -229,7 +243,8 @@ groups: stability: experimental - id: mssqlcompact value: 'mssqlcompact' - brief: 'Microsoft SQL Server Compact' + deprecated: "Removed, use `other_sql` instead." + brief: "Deprecated, Microsoft SQL Server Compact is discontinued." stability: experimental - id: mysql value: 'mysql' @@ -300,7 +315,7 @@ groups: brief: 'Vertica' stability: experimental stability: experimental - - id: client.connections.state + - id: client.connection.state stability: experimental type: allow_custom_values: true @@ -313,7 +328,7 @@ groups: stability: experimental brief: "The state of a connection in the pool" examples: ["idle"] - - id: client.connections.pool.name + - id: client.connection.pool.name type: string stability: experimental brief: > @@ -497,12 +512,6 @@ groups: brief: > This group defines attributes for Elasticsearch. attributes: - - id: elasticsearch.cluster.name - type: string - stability: experimental - brief: > - Represents the identifier of an Elasticsearch cluster. - examples: ["e9106fc68e3044f0b1475b04bf4ffd5f"] - id: elasticsearch.node.name type: string stability: experimental diff --git a/model/registry/deprecated/container.yaml b/model/registry/deprecated/container.yaml index 77f3466f02..63e69621dd 100644 --- a/model/registry/deprecated/container.yaml +++ b/model/registry/deprecated/container.yaml @@ -9,3 +9,23 @@ groups: brief: "Deprecated, use `container.label` instead." stability: experimental deprecated: "Replaced by `container.label`." + - id: container.cpu.state + brief: "Deprecated, use `cpu.mode` instead." + type: + allow_custom_values: true + members: + - id: user + value: 'user' + brief: "When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows)." + stability: experimental + - id: system + value: 'system' + brief: "When CPU is used by the system (host OS)" + stability: experimental + - id: kernel + value: 'kernel' + brief: "When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows)." + stability: experimental + stability: experimental + deprecated: 'Replaced by `cpu.mode`' + examples: [ "user", "kernel" ] diff --git a/model/registry/deprecated/db.yaml b/model/registry/deprecated/db.yaml index 8e24430d20..a58a742881 100644 --- a/model/registry/deprecated/db.yaml +++ b/model/registry/deprecated/db.yaml @@ -84,6 +84,13 @@ groups: brief: 'Deprecated, no general replacement at this time. For Elasticsearch, use `db.elasticsearch.node.name` instead.' deprecated: 'Deprecated, no general replacement at this time. For Elasticsearch, use `db.elasticsearch.node.name` instead.' examples: 'mysql-e26b99z.example.com' + - id: elasticsearch.cluster.name + type: string + stability: experimental + deprecated: Replaced by `db.namespace`. + brief: > + Deprecated, use `db.namespace` instead. + examples: ["e9106fc68e3044f0b1475b04bf4ffd5f"] - id: registry.db.metrics.deprecated type: attribute_group @@ -101,12 +108,32 @@ groups: - id: used value: 'used' stability: experimental - brief: "Deprecated, use `db.client.connections.state` instead." - deprecated: "Replaced by `db.client.connections.state`." + brief: "Deprecated, use `db.client.connection.state` instead." + deprecated: "Replaced by `db.client.connection.state`." examples: ["idle"] - id: pool.name type: string stability: experimental - brief: "Deprecated, use `db.client.connections.pool.name` instead." - deprecated: "Replaced by `db.client.connections.pool.name`." + brief: "Deprecated, use `db.client.connection.pool.name` instead." + deprecated: "Replaced by `db.client.connection.pool.name`." + examples: ["myDataSource"] + - id: db.client.connections.state + stability: experimental + type: + allow_custom_values: true + members: + - id: idle + value: 'idle' + stability: experimental + - id: used + value: 'used' + stability: experimental + brief: "Deprecated, use `db.client.connection.state` instead." + deprecated: "Replaced by `db.client.connection.state`." + examples: ["idle"] + - id: db.client.connections.pool.name + type: string + stability: experimental + brief: "Deprecated, use `db.client.connection.pool.name` instead." + deprecated: "Replaced by `db.client.connection.pool.name`." examples: ["myDataSource"] diff --git a/model/registry/deprecated/gen-ai.yaml b/model/registry/deprecated/gen-ai.yaml new file mode 100644 index 0000000000..ca6abd6732 --- /dev/null +++ b/model/registry/deprecated/gen-ai.yaml @@ -0,0 +1,17 @@ +groups: + - id: registry.gen_ai.deprecated + type: attribute_group + brief: Describes deprecated `gen_ai` attributes. + attributes: + - id: gen_ai.usage.prompt_tokens + type: int + stability: experimental + deprecated: Replaced by `gen_ai.usage.input_tokens` attribute. + brief: "Deprecated, use `gen_ai.usage.input_tokens` instead." + examples: [42] + - id: gen_ai.usage.completion_tokens + type: int + stability: experimental + deprecated: Replaced by `gen_ai.usage.output_tokens` attribute. + brief: "Deprecated, use `gen_ai.usage.output_tokens` instead." + examples: [42] diff --git a/model/registry/deprecated/messaging.yaml b/model/registry/deprecated/messaging.yaml index 2b3c0aad78..5f477018ad 100644 --- a/model/registry/deprecated/messaging.yaml +++ b/model/registry/deprecated/messaging.yaml @@ -24,3 +24,35 @@ groups: Deprecated, use `messaging.client.id` instead. examples: ['client-5', 'myhost@8742@s8083jm'] deprecated: "Replaced by `messaging.client.id`." + - id: messaging.kafka.consumer.group + type: string + brief: > + Deprecated, use `messaging.consumer.group.name` instead. + deprecated: > + Replaced by `messaging.consumer.group.name`. + stability: experimental + examples: 'my-group' + - id: messaging.rocketmq.client_group + type: string + brief: > + Deprecated, use `messaging.consumer.group.name` instead. + stability: experimental + examples: 'myConsumerGroup' + deprecated: > + Replaced by `messaging.consumer.group.name` on the consumer spans. No replacement for producer spans. + - id: messaging.eventhubs.consumer.group + type: string + brief: > + Deprecated, use `messaging.consumer.group.name` instead. + stability: experimental + examples: '$Default' + deprecated: > + Replaced by `messaging.consumer.group.name`. + - id: messaging.servicebus.destination.subscription_name + type: string + brief: > + Deprecated, use `messaging.servicebus.destination.subscription_name` instead. + stability: experimental + examples: 'subscription-a' + deprecated: > + Replaced by `messaging.servicebus.destination.subscription_name`. diff --git a/model/registry/deprecated/process.yaml b/model/registry/deprecated/process.yaml new file mode 100644 index 0000000000..33c5adb0cb --- /dev/null +++ b/model/registry/deprecated/process.yaml @@ -0,0 +1,21 @@ +groups: + - id: registry.process.deprecated + type: attribute_group + brief: "Deprecated process attributes." + attributes: + - id: process.cpu.state + brief: "Deprecated, use `cpu.mode` instead." + deprecated: 'Replaced by `cpu.mode`' + type: + allow_custom_values: true + members: + - id: system + value: 'system' + stability: experimental + - id: user + value: 'user' + stability: experimental + - id: wait + value: 'wait' + stability: experimental + stability: experimental diff --git a/model/registry/deprecated/system.yaml b/model/registry/deprecated/system.yaml index 700023ab57..d220a501b7 100644 --- a/model/registry/deprecated/system.yaml +++ b/model/registry/deprecated/system.yaml @@ -23,3 +23,32 @@ groups: deprecated: "Replaced by `system.process.status`." stability: experimental examples: ["running"] + - id: system.cpu.state + type: + allow_custom_values: true + members: + - id: user + value: 'user' + stability: experimental + - id: system + value: 'system' + stability: experimental + - id: nice + value: 'nice' + stability: experimental + - id: idle + value: 'idle' + stability: experimental + - id: iowait + value: 'iowait' + stability: experimental + - id: interrupt + value: 'interrupt' + stability: experimental + - id: steal + value: 'steal' + stability: experimental + brief: "Deprecated, use `cpu.mode` instead." + stability: experimental + deprecated: 'Replaced by `cpu.mode`' + examples: [ "idle", "interrupt" ] diff --git a/model/registry/gcp.yaml b/model/registry/gcp.yaml index 3b00f7040e..307713df87 100644 --- a/model/registry/gcp.yaml +++ b/model/registry/gcp.yaml @@ -1,4 +1,24 @@ groups: + - id: registry.gcp + prefix: gcp + type: attribute_group + brief: Attributes for Google Cloud + - id: registry.gcp.client + prefix: gcp.client + type: attribute_group + brief: > + Attributes for Google Cloud client libraries. + attributes: + - id: service + type: string + stability: experimental + brief: Identifies the Google Cloud service for which the official client library is intended. + note: > + 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'. + examples: ['appengine', 'run', 'firestore', 'alloydb', 'spanner'] - id: registry.gcp.cloud_run prefix: gcp.cloud_run type: attribute_group diff --git a/model/registry/gen-ai.yaml b/model/registry/gen-ai.yaml index 9e0f3cac12..ce6755a1db 100644 --- a/model/registry/gen-ai.yaml +++ b/model/registry/gen-ai.yaml @@ -3,12 +3,11 @@ groups: prefix: gen_ai type: attribute_group brief: > - This document defines the attributes used to describe telemetry in the context of LLM (Large Language Models) requests and responses. + This document defines the attributes used to describe telemetry in the context of Generative Artificial Intelligence (GenAI) Models requests and responses. attributes: - id: system stability: experimental type: - allow_custom_values: true members: - id: openai stability: experimental @@ -26,67 +25,84 @@ groups: stability: experimental value: "cohere" brief: 'Cohere' - brief: The Generative AI product as identified by the client instrumentation. - note: > + 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 + by `gen_ai.request.model` and `gen_ai.response.model` attributes. + The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` 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`. examples: 'openai' - tag: llm-generic-request - id: request.model stability: experimental type: string - brief: The name of the LLM a request is being made to. + brief: The name of the GenAI model a request is being made to. examples: 'gpt-4' - tag: llm-generic-request - id: request.max_tokens stability: experimental type: int - brief: The maximum number of tokens the LLM generates for a request. + brief: The maximum number of tokens the model generates for a request. examples: [100] - tag: llm-generic-request - id: request.temperature stability: experimental type: double - brief: The temperature setting for the LLM request. + brief: The temperature setting for the GenAI request. examples: [0.0] - tag: llm-generic-request - id: request.top_p stability: experimental type: double - brief: The top_p sampling setting for the LLM request. + brief: The top_p sampling setting for the GenAI request. examples: [1.0] tag: llm-generic-request + - id: request.top_k + stability: experimental + type: double + brief: The top_k sampling setting for the GenAI request. + examples: [1.0] + - id: request.stop_sequences + stability: experimental + type: string[] + brief: List of sequences that the model will use to stop generating further tokens. + examples: ['forest', 'lived'] + - id: request.frequency_penalty + stability: experimental + type: double + brief: The frequency penalty setting for the GenAI request. + examples: [0.1] + - id: request.presence_penalty + stability: experimental + type: double + brief: The presence penalty setting for the GenAI request. + examples: [0.1] - id: response.id stability: experimental type: string brief: The unique identifier for the completion. examples: ['chatcmpl-123'] - tag: llm-generic-response - id: response.model stability: experimental type: string - brief: The name of the LLM a response was generated from. + brief: The name of the model that generated the response. examples: ['gpt-4-0613'] - tag: llm-generic-response - id: response.finish_reasons stability: experimental type: string[] brief: Array of reasons the model stopped generating tokens, corresponding to each generation received. examples: ['stop'] - tag: llm-generic-response - - id: usage.prompt_tokens + - id: usage.input_tokens stability: experimental type: int - brief: The number of tokens used in the LLM prompt. + brief: The number of tokens used in the GenAI input (prompt). examples: [100] - tag: llm-generic-response - - id: usage.completion_tokens + - id: usage.output_tokens stability: experimental type: int - brief: The number of tokens used in the LLM response (completion). + brief: The number of tokens used in the GenAI response (completion). examples: [180] - tag: llm-generic-response - id: token.type stability: experimental type: @@ -104,19 +120,29 @@ groups: - id: prompt stability: experimental type: string - brief: The full prompt sent to an LLM. + brief: The full prompt sent to the GenAI model. note: It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) examples: ["[{'role': 'user', 'content': 'What is the capital of France?'}]"] - tag: llm-generic-events - id: completion stability: experimental type: string - brief: The full response received from the LLM. + brief: The full response received from the GenAI model. note: It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) examples: ["[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]"] - tag: llm-generic-events - id: operation.name stability: experimental - type: string + type: + members: + - id: chat + value: "chat" + brief: 'Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat)' + stability: experimental + - id: text_completion + value: "text_completion" + brief: 'Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions)' + stability: experimental brief: The name of the operation being performed. - examples: ['chat', 'completion'] + note: > + 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. diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index 36be43158b..5c95891653 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -19,6 +19,15 @@ groups: brief: > A unique identifier for the client that consumes or produces a message. examples: ['client-5', 'myhost@8742@s8083jm'] + - id: consumer.group.name + type: string + stability: experimental + brief: > + The name of the consumer group with which a consumer is associated. + note: > + 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. + examples: ['my-group', 'indexer'] - id: destination.name type: string stability: experimental @@ -27,6 +36,15 @@ groups: 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. examples: ['MyQueue', 'MyTopic'] + tag: messaging-generic + - id: destination.subscription.name + type: string + stability: experimental + brief: 'The name of the destination subscription from which a message is consumed.' + note: > + 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. + examples: ['subscription-a'] - id: destination.template type: string stability: experimental @@ -116,16 +134,22 @@ groups: One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. stability: experimental - - id: deliver + - id: process value: "process" brief: > - One or more messages are delivered to or processed by a consumer. + One or more messages are processed by a consumer. stability: experimental - id: settle value: "settle" brief: > One or more messages are settled. stability: experimental + - id: deliver + value: "deliver" + brief: "Deprecated. Use `process` instead." + deprecated: "Replaced by `process`." + stability: experimental + stability: experimental brief: > A string identifying the type of the messaging operation. @@ -196,13 +220,6 @@ groups: brief: > This group describes attributes specific to Apache Kafka. attributes: - - id: kafka.consumer.group - type: string - stability: experimental - brief: > - Name of the Kafka Consumer Group that is handling the message. - Only applies to consumers, not producers. - examples: 'my-group' - id: kafka.message.key type: string stability: experimental @@ -248,12 +265,6 @@ groups: brief: > This group describes attributes specific to RocketMQ. attributes: - - id: rocketmq.client_group - type: string - stability: experimental - brief: > - Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. - examples: 'myConsumerGroup' - id: rocketmq.consumption_model type: allow_custom_values: false @@ -376,12 +387,6 @@ groups: brief: > The UTC epoch seconds at which the message has been accepted and stored in the entity. examples: 1701393730 - - id: servicebus.destination.subscription_name - type: string - stability: experimental - brief: > - The name of the subscription in the topic messages are received from. - examples: "mySubscription" - id: servicebus.disposition_status brief: > Describes the [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). @@ -417,9 +422,3 @@ groups: brief: > The UTC epoch seconds at which the message has been accepted and stored in the entity. examples: 1701393730 - - id: eventhubs.consumer.group - type: string - stability: experimental - brief: > - The name of the consumer group the event consumer is associated with. - examples: 'indexer' diff --git a/model/registry/process.yaml b/model/registry/process.yaml index 54c9a6fb40..d9c0575ae7 100644 --- a/model/registry/process.yaml +++ b/model/registry/process.yaml @@ -130,8 +130,7 @@ groups: type: string stability: experimental brief: > - The name of the runtime of this process. For compiled native binaries, - this SHOULD be the name of the compiler. + The name of the runtime of this process. examples: ['OpenJDK Runtime Environment'] - id: runtime.version type: string @@ -196,26 +195,3 @@ groups: value: 'minor' stability: experimental stability: experimental - - - id: registry.process.cpu - prefix: process.cpu - type: attribute_group - brief: > - Attributes for process CPU - attributes: - - id: state - brief: > - The CPU state of the process. - type: - allow_custom_values: true - members: - - id: system - value: 'system' - stability: experimental - - id: user - value: 'user' - stability: experimental - - id: wait - value: 'wait' - stability: experimental - stability: experimental diff --git a/model/registry/system.yaml b/model/registry/system.yaml index d407f96d56..790a1374af 100644 --- a/model/registry/system.yaml +++ b/model/registry/system.yaml @@ -16,34 +16,6 @@ groups: type: attribute_group brief: "Describes System CPU attributes" attributes: - - id: state - type: - allow_custom_values: true - members: - - id: user - value: 'user' - stability: experimental - - id: system - value: 'system' - stability: experimental - - id: nice - value: 'nice' - stability: experimental - - id: idle - value: 'idle' - stability: experimental - - id: iowait - value: 'iowait' - stability: experimental - - id: interrupt - value: 'interrupt' - stability: experimental - - id: steal - value: 'steal' - stability: experimental - brief: "The state of the CPU" - stability: experimental - examples: ["idle", "interrupt"] - id: logical_number type: int stability: experimental diff --git a/model/registry/v8js.yaml b/model/registry/v8js.yaml new file mode 100644 index 0000000000..a03cbe7143 --- /dev/null +++ b/model/registry/v8js.yaml @@ -0,0 +1,54 @@ +groups: + - id: registry.v8js + type: attribute_group + brief: Describes V8 JS Engine Runtime related attributes. + prefix: v8js + attributes: + - id: gc.type + stability: experimental + brief: The type of garbage collection. + type: + members: + - id: major + value: 'major' + brief: 'Major (Mark Sweep Compact).' + stability: experimental + - id: minor + value: 'minor' + brief: 'Minor (Scavenge).' + stability: experimental + - id: incremental + value: 'incremental' + brief: 'Incremental (Incremental Marking).' + stability: experimental + - id: weakcb + value: 'weakcb' + brief: 'Weak Callbacks (Process Weak Callbacks).' + stability: experimental + - id: heap.space.name + stability: experimental + brief: The name of the space type of heap memory. + note: > + Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + type: + members: + - id: new_space + value: 'new_space' + brief: 'New memory space.' + stability: experimental + - id: old_space + value: 'old_space' + brief: 'Old memory space.' + stability: experimental + - id: code_space + value: 'code_space' + brief: 'Code memory space.' + stability: experimental + - id: map_space + value: 'map_space' + brief: 'Map memory space.' + stability: experimental + - id: large_object_space + value: 'large_object_space' + brief: 'Large object memory space.' + stability: experimental diff --git a/model/trace/database.yaml b/model/trace/database.yaml index 5194bb6643..24d92636dd 100644 --- a/model/trace/database.yaml +++ b/model/trace/database.yaml @@ -13,10 +13,6 @@ groups: Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). - note: - 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. - ref: db.query.parameter requirement_level: opt_in @@ -29,6 +25,7 @@ groups: requirement_level: recommended: > SHOULD be collected by default only if there is sanitization that excludes sensitive information. + See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). - ref: db.query.parameter requirement_level: opt_in - ref: db.collection.name @@ -226,7 +223,9 @@ groups: requirement_level: required - ref: db.operation.name requirement_level: required - note: This SHOULD be the endpoint identifier for the request. + note: > + 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)). examples: [ 'search', 'ml.close_job', 'cat.aliases' ] - ref: url.full requirement_level: required @@ -238,16 +237,24 @@ groups: sensitive information. brief: The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. examples: [ '"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"' ] + - ref: db.collection.name + requirement_level: recommended + brief: The index or data stream against which the query is executed. + note: > + 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. + examples: [ 'my_index', 'index1, index2' ] - ref: server.address - ref: server.port - - ref: db.elasticsearch.cluster.name - requirement_level: - recommended: > - When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. + - ref: db.namespace + note: > + When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. + brief: The name of the Elasticsearch cluster which the client connects to. + requirement_level: recommended - ref: db.elasticsearch.node.name - requirement_level: - recommended: > - When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header. + note: > + When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header. + requirement_level: recommended - ref: db.elasticsearch.path_parts requirement_level: conditionally_required: when the url has dynamic values diff --git a/model/trace/gen-ai.yaml b/model/trace/gen-ai.yaml index bf1d112e37..d036c19755 100644 --- a/model/trace/gen-ai.yaml +++ b/model/trace/gen-ai.yaml @@ -1,41 +1,46 @@ groups: - - id: gen_ai.request + - id: trace.gen_ai.client type: span brief: > - A request to an LLM is modeled as a span in a trace. The span name should be a low cardinality value representing the request made to an LLM, like the name of the API endpoint being called. + Describes GenAI operation span. attributes: - ref: gen_ai.system requirement_level: required - note: > - If not using a vendor-supplied model, provide a custom friendly name, such as a name of the company or project. - If the instrumetnation reports any attributes specific to a custom model, the value provided in the `gen_ai.system` SHOULD match the custom attribute namespace segment. - For example, if `gen_ai.system` is set to `the_best_llm`, custom attributes should be added in the `gen_ai.the_best_llm.*` namespace. - If none of above options apply, the instrumentation should set `_OTHER`. - ref: gen_ai.request.model requirement_level: required note: > - The name of the LLM a request is being made to. If the LLM is supplied by a vendor, - then the value must be the exact name of the model requested. If the LLM is a fine-tuned + 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. + - ref: gen_ai.operation.name + requirement_level: required - ref: gen_ai.request.max_tokens requirement_level: recommended - ref: gen_ai.request.temperature requirement_level: recommended - ref: gen_ai.request.top_p requirement_level: recommended + - ref: gen_ai.request.top_k + requirement_level: recommended + - ref: gen_ai.request.stop_sequences + requirement_level: recommended + - ref: gen_ai.request.frequency_penalty + requirement_level: recommended + - ref: gen_ai.request.presence_penalty + requirement_level: recommended - ref: gen_ai.response.id requirement_level: recommended - ref: gen_ai.response.model requirement_level: recommended note: > - If available. The name of the LLM serving a response. If the LLM is supplied by a vendor, - then the value must be the exact name of the model actually used. If the LLM is a + 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. - ref: gen_ai.response.finish_reasons requirement_level: recommended - - ref: gen_ai.usage.prompt_tokens + - ref: gen_ai.usage.input_tokens requirement_level: recommended - - ref: gen_ai.usage.completion_tokens + - ref: gen_ai.usage.output_tokens requirement_level: recommended events: - gen_ai.content.prompt @@ -45,7 +50,7 @@ groups: name: gen_ai.content.prompt type: event brief: > - In the lifetime of an LLM span, events for prompts sent and completions received + In the lifetime of an GenAI span, events for prompts sent and completions received may be created, depending on the configuration of the instrumentation. attributes: - ref: gen_ai.prompt @@ -58,7 +63,7 @@ groups: name: gen_ai.content.completion type: event brief: > - In the lifetime of an LLM span, events for prompts sent and completions received + In the lifetime of an GenAI span, events for prompts sent and completions received may be created, depending on the configuration of the instrumentation. attributes: - ref: gen_ai.completion diff --git a/model/trace/instrumentation/gcp-client.yml b/model/trace/instrumentation/gcp-client.yml new file mode 100644 index 0000000000..08a6ac311e --- /dev/null +++ b/model/trace/instrumentation/gcp-client.yml @@ -0,0 +1,12 @@ +groups: +- id: gcp.client.attributes + type: attribute_group + brief: Conventions for official Google Cloud client libraries. + prefix: gcp.client + stability: experimental + attributes: + - ref: gcp.client.service + requirement_level: + conditionally_required: + Required if and only if the instrumentation library is an official, + Google-provided GCP and/or Firebase client library. diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index e20ecc3e00..52bf65c542 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -1,32 +1,4 @@ groups: - - id: messaging.message - type: attribute_group - brief: 'Semantic convention describing per-message attributes populated on messaging spans or links.' - attributes: - - ref: messaging.destination.name - - ref: messaging.message.id - - ref: messaging.message.conversation_id - - ref: messaging.message.envelope.size - - ref: messaging.message.body.size - - - id: messaging.destination - type: attribute_group - brief: 'Semantic convention for attributes that describe messaging destination on broker' - note: | - Destination attributes should be set on publish, receive, or other spans - describing messaging operations. - - Destination attributes should be set when the messaging operation handles - single messages. When the operation handles a batch of messages, - the destination attributes should only be applied when the attribute value - applies to all messages in the batch. - In other cases, destination attributes may be set on links. - attributes: - - ref: messaging.destination.name - - ref: messaging.destination.template - - ref: messaging.destination.temporary - - ref: messaging.destination.anonymous - - id: messaging.destination_publish prefix: messaging.destination_publish type: attribute_group @@ -45,6 +17,7 @@ groups: In other cases, destination attributes may be set on links. attributes: - ref: messaging.destination_publish.name + sampling_relevant: true - ref: messaging.destination_publish.anonymous - id: attributes.messaging.trace.minimal @@ -53,17 +26,27 @@ groups: Defines minimal set of attributes used by all messaging systems. extends: attributes.messaging.common.minimal attributes: - - ref: messaging.operation.type - requirement_level: required - ref: messaging.operation.name + requirement_level: required + sampling_relevant: true + - ref: messaging.operation.type requirement_level: - recommended: If the operation is not sufficiently described by `messaging.operation.type`. + conditionally_required: If applicable. + sampling_relevant: true - ref: messaging.destination.name requirement_level: conditionally_required: If span describes operation on a single message or if the value applies to all messages in the batch. + sampling_relevant: true - ref: messaging.message.id requirement_level: recommended: If span describes operation on a single message. + - ref: server.address + sampling_relevant: true + - ref: server.port + sampling_relevant: true + # TODO: add messaging.system once https://github.com/open-telemetry/build-tools/issues/192 is implemented + # - ref: messaging.system + # sampling_relevant: true - id: messaging type: span @@ -73,23 +56,33 @@ groups: attributes: - ref: messaging.system requirement_level: required + sampling_relevant: true - ref: messaging.client.id - requirement_level: - recommended: If a client id is available + requirement_level: recommended - ref: messaging.destination.partition.id requirement_level: recommended: When applicable. + sampling_relevant: true - ref: messaging.destination.template requirement_level: conditionally_required: > If available. Instrumentations MUST NOT use `messaging.destination.name` as template unless low-cardinality of destination name is guaranteed. + sampling_relevant: true - ref: messaging.destination.temporary requirement_level: conditionally_required: If value is `true`. When missing, the value is assumed to be `false`. - ref: messaging.destination.anonymous requirement_level: conditionally_required: If value is `true`. When missing, the value is assumed to be `false`. + - ref: messaging.consumer.group.name + requirement_level: + conditionally_required: If applicable. + sampling_relevant: true + - ref: messaging.destination.subscription.name + requirement_level: + conditionally_required: If applicable. + sampling_relevant: true - ref: messaging.message.conversation_id - ref: messaging.message.envelope.size - ref: messaging.message.body.size @@ -146,14 +139,18 @@ groups: brief: > Attributes for Apache Kafka attributes: + - ref: messaging.consumer.group.name + brief: "Kafka [consumer group id](https://docs.confluent.io/platform/current/clients/consumer.html)." + note: "" + sampling_relevant: true - ref: messaging.destination.partition.id brief: > String representation of the partition id the message (or batch) is sent to or received from. requirement_level: recommended + sampling_relevant: true - ref: messaging.kafka.message.key requirement_level: recommended: If span describes operation on a single message. - - ref: messaging.kafka.consumer.group - ref: messaging.kafka.message.offset requirement_level: recommended: If span describes operation on a single message. @@ -174,9 +171,12 @@ groups: brief: > Attributes for Apache RocketMQ attributes: - - ref: messaging.rocketmq.namespace + - ref: messaging.consumer.group.name + brief: "RocketMQ [consumer group name](https://rocketmq.apache.org/docs/domainModel/07consumergroup)." + note: "" + sampling_relevant: true requirement_level: required - - ref: messaging.rocketmq.client_group + - ref: messaging.rocketmq.namespace requirement_level: required - ref: messaging.rocketmq.message.delivery_timestamp requirement_level: @@ -204,6 +204,10 @@ groups: brief: > Attributes for Google Cloud Pub/Sub attributes: + - ref: messaging.destination.subscription.name + brief: "Google Pub/Sub [subscription name](https://cloud.google.com/pubsub/docs/subscription-overview)." + note: "" + sampling_relevant: true - ref: messaging.gcp_pubsub.message.ordering_key requirement_level: conditionally_required: If the message type has an ordering key set. @@ -213,21 +217,32 @@ groups: - ref: messaging.batch.message_count requirement_level: conditionally_required: If the span describes an operation on a batch of messages. + - ref: messaging.operation.name + note: | + 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 + - `send` for publishing operations + - `modack` for extending the lease for a single message or batch of messages + - `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#common-messaging-operations) - id: messaging.servicebus type: attribute_group extends: attributes.messaging.trace.minimal brief: > Attributes for Azure Service Bus attributes: - - ref: messaging.operation.name + - ref: messaging.destination.subscription.name + brief: "Azure Service Bus [subscription name](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-queues-topics-subscriptions#topics-and-subscriptions)." + note: "" + sampling_relevant: true + requirement_level: + conditionally_required: If messages are received from the subscription. - ref: messaging.servicebus.message.delivery_count requirement_level: conditionally_required: If delivery count is available and is bigger than 0. - ref: messaging.servicebus.message.enqueued_time - - ref: messaging.servicebus.destination.subscription_name - requirement_level: - conditionally_required: If messages are received from the subscription. - ref: messaging.servicebus.disposition_status requirement_level: conditionally_required: if and only if `messaging.operation` is `settle`. @@ -236,22 +251,56 @@ groups: - ref: messaging.batch.message_count requirement_level: conditionally_required: If the span describes an operation on a batch of messages. + - ref: messaging.operation.name + brief: Azure Service Bus operation name. + note: | + The operation name SHOULD match one of the following values: + + - sender operations: `send`, `schedule`, `cancel_scheduled` + - transaction operations: `create_transaction`, `commit_transaction`, `rollback_transaction` + - receiver operation: `receive`, `peek`, `receive_deferred`, `renew_message_lock` + - settlement operations: `abandon`, `complete`, `defer`, `dead_letter`, `delete` + - session operations: `accept_session`, `get_session_state`, `set_session_state`, `renew_session_lock` + + If none of the above operation names apply, the attribute SHOULD be set + to the name of the client method in snake_case. + + examples: ['send', 'receive', 'complete', 'process', 'peek'] + - id: messaging.eventhubs type: attribute_group extends: attributes.messaging.trace.minimal brief: > Attributes for Azure Event Hubs attributes: - - ref: messaging.operation.name + - 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)." + note: "" + requirement_level: + conditionally_required: On consumer spans. + sampling_relevant: true - ref: messaging.destination.partition.id brief: > String representation of the partition id messages are sent to or received from, unique within the Event Hub. requirement_level: conditionally_required: If available. + sampling_relevant: true - ref: messaging.eventhubs.message.enqueued_time - - ref: messaging.eventhubs.consumer.group - requirement_level: - conditionally_required: If not default ("$Default"). - ref: messaging.batch.message_count requirement_level: conditionally_required: If the span describes an operation on a batch of messages. + - ref: messaging.operation.name + brief: Azure Event Hubs operation name. + examples: ['send', 'receive', 'checkpoint'] + note: | + The operation name SHOULD match one of the following values: + + - `send` + - `receive` + - `process` + - `checkpoint` + - `get_partition_properties` + - `get_event_hub_properties` + + If none of the above operation names apply, the attribute SHOULD be set + to the name of the client method in snake_case. diff --git a/schema-next.yaml b/schema-next.yaml index 32ab76d055..b2d310bd77 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -2,6 +2,62 @@ file_format: 1.1.0 schema_url: https://opentelemetry.io/schemas/next versions: next: + all: + changes: + # 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.evenhubs.consumer.group: messaging.consumer.group.name + message.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 1.26.0: metrics: changes: diff --git a/templates/registry/markdown/weaver.yaml b/templates/registry/markdown/weaver.yaml index 19cbd089a6..f698ae6754 100644 --- a/templates/registry/markdown/weaver.yaml +++ b/templates/registry/markdown/weaver.yaml @@ -10,6 +10,7 @@ acronyms: - iOS - AWS - CloudEvents + - CPU - CosmosDB - DynamoDB - ECS @@ -19,6 +20,7 @@ acronyms: - GCE - HTTP - JVM + - NodeJS - OCI - OTel - OpenTracing