diff --git a/.chloggen/564.yaml b/.chloggen/564.yaml new file mode 100644 index 0000000000..777f5f8b7b --- /dev/null +++ b/.chloggen/564.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: process + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add additional attributes to process attribute registry + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [564] + +# (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/634.yaml b/.chloggen/634.yaml new file mode 100644 index 0000000000..16b837ff88 --- /dev/null +++ b/.chloggen/634.yaml @@ -0,0 +1,25 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: messaging + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: "Add a GCP Pub/Sub unary pull example and the new GCP messaging attributes: +- `messaging.gcp_pubsub.message.ack_deadline`, +- `messaging.gcp_pubsub.message.ack_id`, +- `messaging.gcp_pubsub.message.delivery_attempt`" + +# 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: [527] + +# (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/735.yaml b/.chloggen/735.yaml new file mode 100644 index 0000000000..e28402e049 --- /dev/null +++ b/.chloggen/735.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: Add `db.client.operation.duration` metric + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [512] + +# (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/814.yaml b/.chloggen/814.yaml new file mode 100644 index 0000000000..10dc2529f6 --- /dev/null +++ b/.chloggen/814.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: messaging +note: Adds `messaging.destination.partition.id`` to the messaging attributes +issues: [ 814 ] diff --git a/.chloggen/862.yaml b/.chloggen/862.yaml new file mode 100644 index 0000000000..828a88899e --- /dev/null +++ b/.chloggen/862.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: exception +note: Replace constraints with requirement levels on exceptions. +issues: [ 862 ] diff --git a/.chloggen/863.yaml b/.chloggen/863.yaml new file mode 100644 index 0000000000..6dc53c5dcf --- /dev/null +++ b/.chloggen/863.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: process +note: Replace constraints with requirement_level in process attributes. +issues: [ 863 ] diff --git a/.chloggen/866.yaml b/.chloggen/866.yaml new file mode 100644 index 0000000000..43ee49568b --- /dev/null +++ b/.chloggen/866.yaml @@ -0,0 +1,4 @@ +change_type: breaking +component: db +note: Rename `db.statement` to `db.query.text` and introduce `db.query.parameter.` +issues: [ 716 ] diff --git a/.chloggen/870.yaml b/.chloggen/870.yaml new file mode 100644 index 0000000000..dd5dc6fe37 --- /dev/null +++ b/.chloggen/870.yaml @@ -0,0 +1,4 @@ +change_type: breaking +component: db +note: Renames `db.sql.table`, `db.cassandra.table`, `db.mongodb.collection`, and `db.cosmosdb.container` attributes to `db.collection.name` +issues: [ 870 ] diff --git a/.chloggen/875.yaml b/.chloggen/875.yaml new file mode 100644 index 0000000000..8d75a96c85 --- /dev/null +++ b/.chloggen/875.yaml @@ -0,0 +1,4 @@ +change_type: breaking +component: db +note: Rename `db.operation` to `db.operation.name`. +issues: [ 884 ] diff --git a/.chloggen/890.yaml b/.chloggen/890.yaml new file mode 100644 index 0000000000..4c3e5ce030 --- /dev/null +++ b/.chloggen/890.yaml @@ -0,0 +1,4 @@ +change_type: breaking +component: messaging +note: Rename `messaging.operation` to `messaging.operation.type`, add `messaging.operation.name`. +issues: [ 890 ] diff --git a/.chloggen/894.yaml b/.chloggen/894.yaml new file mode 100644 index 0000000000..23f73b1f2c --- /dev/null +++ b/.chloggen/894.yaml @@ -0,0 +1,4 @@ +change_type: breaking +component: db +note: Deprecate the `db.user` attribute. +issues: [ 885 ] diff --git a/.chloggen/910.yaml b/.chloggen/910.yaml new file mode 100644 index 0000000000..fbfbe2cd73 --- /dev/null +++ b/.chloggen/910.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: db +note: Reorganize DB conventions to be shared across span and metric conventions. +issues: [ 910 ] diff --git a/.chloggen/911.yaml b/.chloggen/911.yaml new file mode 100644 index 0000000000..b132291a62 --- /dev/null +++ b/.chloggen/911.yaml @@ -0,0 +1,4 @@ +change_type: breaking +component: db +note: Rename `db.name` and `db.redis.database_index` to `db.namespace`, deprecate `db.mssql.instance_name`. +issues: [ 885 ] diff --git a/.chloggen/917.yaml b/.chloggen/917.yaml new file mode 100644 index 0000000000..b4f7c596bb --- /dev/null +++ b/.chloggen/917.yaml @@ -0,0 +1,18 @@ +change_type: enhancement +component: all + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Migrate Attribute Registry to be completely autogenerated. + +# 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: [197] + +# (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: | + Migrate to using weaver for markdown generation (snippet + registry). + The entirety of the registry now is generated using weaver with templates + under the `templates/` directory. Snippets still require a hardcoded + command. diff --git a/.chloggen/931.yaml b/.chloggen/931.yaml new file mode 100644 index 0000000000..ad215bd516 --- /dev/null +++ b/.chloggen/931.yaml @@ -0,0 +1,7 @@ +change_type: enhancement + +component: http + +note: List all HTTP client and server attributes in the corresponding table, remove common attributes from yaml and markdown. + +issues: [928] diff --git a/.chloggen/972.yaml b/.chloggen/972.yaml new file mode 100644 index 0000000000..9cebfe9f27 --- /dev/null +++ b/.chloggen/972.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: Remove `db.instance.id`. For Elasticsearch, replace with `db.elasticsearch.node.name`. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [ 972 ] + +# (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/974.yaml b/.chloggen/974.yaml new file mode 100644 index 0000000000..5be41e3283 --- /dev/null +++ b/.chloggen/974.yaml @@ -0,0 +1,7 @@ +change_type: breaking + +component: db + +note: Clarify database span name format and fallback values. + +issues: [974, 704] diff --git a/.chloggen/975.yaml b/.chloggen/975.yaml new file mode 100644 index 0000000000..f67fc63c34 --- /dev/null +++ b/.chloggen/975.yaml @@ -0,0 +1,7 @@ +change_type: enhancement + +component: db + +note: Add `error.type` attribute to the database span and operation duration metric. + +issues: [975] diff --git a/.chloggen/989.yaml b/.chloggen/989.yaml new file mode 100644 index 0000000000..d0124672bc --- /dev/null +++ b/.chloggen/989.yaml @@ -0,0 +1,7 @@ +change_type: enhancement + +component: http + +note: List experimental HTTP attributes applicable to HTTP client and server spans. + +issues: [989] diff --git a/.chloggen/TEMPLATE.yaml b/.chloggen/TEMPLATE.yaml new file mode 100644 index 0000000000..b094f4d184 --- /dev/null +++ b/.chloggen/TEMPLATE.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: + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: + +# 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: [] + +# (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/config.yaml b/.chloggen/config.yaml new file mode 100644 index 0000000000..411f32d3a5 --- /dev/null +++ b/.chloggen/config.yaml @@ -0,0 +1,24 @@ +# The directory that stores individual changelog entries. +# Each entry is stored in a dedicated yaml file. +# - 'make chlog-new' will copy the 'template_yaml' to this directory as a new entry file. +# - 'make chlog-validate' will validate that all entry files are valid. +# - 'make chlog-update' will read and delete all entry files in this directory, and update 'changelog_md'. + +# Specify as relative path from root of repo. +# (Optional) Default: .chloggen +entries_dir: .chloggen + +# This file is used as the input for individual changelog entries. +# Specify as relative path from root of repo. +# (Optional) Default: .chloggen/TEMPLATE.yaml +template_yaml: .chloggen/TEMPLATE.yaml + +# The CHANGELOG file or files to which 'chloggen update' will write new entries +# (Optional) Default filename: CHANGELOG.md +change_logs: + user: CHANGELOG.md + +# The default change_log or change_logs to which an entry should be added. +# If 'change_logs' is specified in this file, and no value is specified for 'default_change_logs', +# then 'change_logs' MUST be specified in every entry file. +default_change_logs: [user] diff --git a/.chloggen/db_client_connection_metric.yaml b/.chloggen/db_client_connection_metric.yaml new file mode 100755 index 0000000000..0c3c9222d8 --- /dev/null +++ b/.chloggen/db_client_connection_metric.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: > + Rename `db.client.connections.*` metric namespace to `db.client.connection.*` and + rename `db.client.connection.usage` to `db.client.connection.count`. + +# 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: [201, 967] + +# (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_metrics.yaml b/.chloggen/db_metrics.yaml new file mode 100755 index 0000000000..0e8468e967 --- /dev/null +++ b/.chloggen/db_metrics.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: 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 `pool.name` to `db.client.connections.pool.name` and `state` to `db.client.connections.state`. + +# 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: [909] + +# (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/decouple_shared_memory_metric.yaml b/.chloggen/decouple_shared_memory_metric.yaml new file mode 100755 index 0000000000..5f5fb7be4e --- /dev/null +++ b/.chloggen/decouple_shared_memory_metric.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: Deprecate `shared` from `system.memory.state` values and make it a standalone metric + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [522] + +# (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/device_app_lifecycle.yaml b/.chloggen/device_app_lifecycle.yaml new file mode 100644 index 0000000000..18fdf8a931 --- /dev/null +++ b/.chloggen/device_app_lifecycle.yaml @@ -0,0 +1,26 @@ +# 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: device.app.lifecycle + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: > + Reformat and update the `device.app.lifecycle` event description adds constraints for the possible values of + the `android.state` and `ios.state`. + +# 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: [794] + +# (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: > + 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. diff --git a/.chloggen/first-gen-ai.yaml b/.chloggen/first-gen-ai.yaml new file mode 100755 index 0000000000..62dec0d56e --- /dev/null +++ b/.chloggen/first-gen-ai.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: new_component + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: gen-ai + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Introducing semantic conventions for GenAI clients. + +# 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: [327] + +# (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/k8s-status.yaml b/.chloggen/k8s-status.yaml new file mode 100755 index 0000000000..cfbbe489ea --- /dev/null +++ b/.chloggen/k8s-status.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: "k8s" + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: add container.status.last_terminated_reason resource 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: [922] + +# (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/rpc_registry.yaml b/.chloggen/rpc_registry.yaml new file mode 100755 index 0000000000..1401a385e6 --- /dev/null +++ b/.chloggen/rpc_registry.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: rpc + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Rename`message.*` attributes under `rpc` to `rpc.message.*`. Deprecate old `message.*` attributes. + +# 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: [854] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 4ef9633c60..132862aac6 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -6,13 +6,13 @@ # # Learn about membership in OpenTelemetry community: # https://github.com/open-telemetry/community/blob/main/community-membership.md -# # -# Learn about CODEOWNERS file format: -# https://help.github.com/en/articles/about-code-owners +# +# Learn about CODEOWNERS file format: +# https://help.github.com/articles/about-code-owners # -# Global owners, will be the owners for everything in the repo. Membership is tracked via https://github.com/open-telemetry/community/blob/main/community-members.md +# Global owners, will be the owners for everything in the repo. Membership is tracked via https://github.com/open-telemetry/community/blob/main/community-members.md * @open-telemetry/specs-semconv-maintainers @open-telemetry/specs-semconv-approvers # Schemas and schema file tooling @@ -28,11 +28,52 @@ /docs/logs/ @open-telemetry/specs-semconv-approvers @tigrannajaryan # JVM semantic conventions approvers -/model/metrics/process-runtime-jvm-metrics.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers -/model/metrics/process-runtime-jvm-metrics-experimental.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers +/model/metrics/jvm-* @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers +/docs/jvm/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers # HTTP semantic conventions approvers /model/metrics/http.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers /model/trace/http.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/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/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 +/docs/http/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers + +# System semantic conventions approvers +/docs/system/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers +/model/metrics/system-* @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers +/docs/resource/host.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers +/model/resource/host.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers + +# Mobile semantic conventions approvers +/docs/mobile/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-approvers +/model/logs/mobile* @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-approvers + +# K8s semantic conventions approvers +/docs/resource/k8s.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers +/model/resource/k8s.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers +/model/registry/k8s.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers + +# Container semantic conventions approvers +/docs/resource/container.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers +/model/resource/container.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers +/model/registry/container.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers +/model/registry/oci.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers + +# .NET semantic conventions approvers +/model/metrics/dotnet/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers +/model/registry/aspnetcore.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers +/model/registry/signalr.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers +/docs/dotnet/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers + +# Gen-AI semantic conventions approvers +/model/registry/gen-ai.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-llm-approvers +/model/metrics/gen-ai.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-llm-approvers +/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 diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml new file mode 100644 index 0000000000..af486e4502 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -0,0 +1,100 @@ +name: Bug report +description: Create a report to help us improve +labels: ["bug", "triage:needs-triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this bug report! Please make sure to fill out the entire form below, providing as much context as you can in order to help us triage and track down your bug as quickly as possible. + + Before filing a bug, please be sure you have searched through [existing bugs](https://github.com/open-telemetry/semantic-conventions/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Abug) to see if an existing issue covers your bug. + - type: dropdown + id: area + attributes: + label: Area(s) + description: Which area(s) does your bug report concern? If none fits, please select `area:other` + multiple: true + options: + - area:other + # NOTE: The list below is autogenerated using `make generate-gh-issue-templates` + # DO NOT manually edit it. + # Start semconv area list + - area:android + - area:aspnetcore + - area:aws + - area:browser + - area:client + - area:cloud + - area:cloudevents + - area:code + - area:container + - area:db + - area:deployment + - area:destination + - area:device + - area:disk + - area:dns + - area:enduser + - area:error + - area:event + - area:exception + - area:faas + - area:feature-flag + - area:file + - area:gcp + - area:gen-ai + - area:graphql + - area:heroku + - area:host + - area:http + - area:jvm + - area:k8s + - area:log + - area:messaging + - area:network + - area:oci + - area:opentracing + - area:os + - area:otel + - area:peer + - area:process + - area:rpc + - area:server + - area:service + - area:session + - area:signalr + - area:source + - area:system + - area:telemetry + - area:thread + - area:tls + - area:url + - area:user-agent + - area:webengine + # End semconv area list + - type: textarea + attributes: + label: What happened? + description: Please provide as much detail as you reasonably can. + value: | + ## Description + + ## Steps to Reproduce (if any) + + ## Expected Result + + ## Actual Result + validations: + required: true + + - type: input + attributes: + label: Semantic convention version + description: What version did you use? (e.g., `v1.24.0`, `1eb551b`, etc) + validations: + required: true + + - type: textarea + attributes: + label: Additional context + description: Any additional information you think may be relevant to this issue. diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml new file mode 100644 index 0000000000..3d00899d2d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -0,0 +1,87 @@ +name: Propose changes to existing conventions +description: Propose changes you'd like to be added to existing conventions +labels: ["enhancement", "triage:needs-triage"] +body: + - type: dropdown + id: area + attributes: + label: Area(s) + description: Which area(s) does your change request concern? + multiple: true + options: + # NOTE: The list below is autogenerated using `make generate-gh-issue-templates` + # DO NOT manually edit it. + # Start semconv area list + - area:android + - area:aspnetcore + - area:aws + - area:browser + - area:client + - area:cloud + - area:cloudevents + - area:code + - area:container + - area:db + - area:deployment + - area:destination + - area:device + - area:disk + - area:dns + - area:enduser + - area:error + - area:event + - area:exception + - area:faas + - area:feature-flag + - area:file + - area:gcp + - area:gen-ai + - area:graphql + - area:heroku + - area:host + - area:http + - area:jvm + - area:k8s + - area:log + - area:messaging + - area:network + - area:oci + - area:opentracing + - area:os + - area:otel + - area:peer + - area:process + - area:rpc + - area:server + - area:service + - area:session + - area:signalr + - area:source + - area:system + - area:telemetry + - area:thread + - area:tls + - area:url + - area:user-agent + - area:webengine + # End semconv area list + - type: textarea + attributes: + label: Is your change request related to a problem? Please describe. + description: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + validations: + required: true + - type: textarea + attributes: + label: Describe the solution you'd like + description: A clear and concise description of what you want to happen. + validations: + required: true + - type: textarea + attributes: + label: Describe alternatives you've considered + description: A clear and concise description of any alternative solutions or features you've considered. + - type: textarea + attributes: + label: Additional context + description: Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml new file mode 100644 index 0000000000..3985923373 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -0,0 +1,96 @@ +name: Propose new semantic conventions +description: Propose new conventions you'd like to be part of the OpenTelemetry project +labels: ["enhancement", "triage:needs-triage", "experts needed"] +body: + - type: markdown + attributes: + value: | + Please make sure to fill out the entire form below, providing as much context as you can in order to help us triage the proposal as quickly as possible. + + Before filing the proposal, please be sure you have searched through [existing issues](https://github.com/open-telemetry/semantic-conventions/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aenhancement+label%3Aarea:new) to see if an existing issue covers your proposal. + + Additionally, make sure to read and follow the guidelines on [Project Proposal](https://github.com/open-telemetry/community/blob/main/project-management.md#project-management), in case the proposal is for a new set of conventions/working group. + - type: dropdown + id: area + attributes: + label: Area(s) + description: Which area(s) does your new conventions concern? If none fits, please select `area:new` + multiple: true + options: + - area:new + # NOTE: The list below is autogenerated using `make generate-gh-issue-templates` + # DO NOT manually edit it. + # Start semconv area list + - area:android + - area:aspnetcore + - area:aws + - area:browser + - area:client + - area:cloud + - area:cloudevents + - area:code + - area:container + - area:db + - area:deployment + - area:destination + - area:device + - area:disk + - area:dns + - area:enduser + - area:error + - area:event + - area:exception + - area:faas + - area:feature-flag + - area:file + - area:gcp + - area:gen-ai + - area:graphql + - area:heroku + - area:host + - area:http + - area:jvm + - area:k8s + - area:log + - area:messaging + - area:network + - area:oci + - area:opentracing + - area:os + - area:otel + - area:peer + - area:process + - area:rpc + - area:server + - area:service + - area:session + - area:signalr + - area:source + - area:system + - area:telemetry + - area:thread + - area:tls + - area:url + - area:user-agent + - area:webengine + # End semconv area list + - type: textarea + attributes: + label: Is your change request related to a problem? Please describe. + description: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + validations: + required: true + - type: textarea + attributes: + label: Describe the solution you'd like + description: A clear and concise description of what you want to happen. + validations: + required: true + - type: textarea + attributes: + label: Describe alternatives you've considered + description: A clear and concise description of any alternative solutions or features you've considered. + - type: textarea + attributes: + label: Additional context + description: Add any other context or screenshots about the feature request here. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000000..0ea068d59c --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,14 @@ +Fixes # + +## Changes + +Please provide a brief description of the changes here. + +Note: if the PR is touching an area that is not listed in the [existing areas](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md), or the area does not have sufficient [domain experts coverage](https://github.com/open-telemetry/semantic-conventions/blob/main/.github/CODEOWNERS), the PR might be tagged as [experts needed](https://github.com/open-telemetry/semantic-conventions/labels/experts%20needed) and move slowly until experts are identified. + +## Merge requirement checklist + +* [ ] [CONTRIBUTING.md](https://github.com/open-telemetry/semantic-conventions/blob/main/CONTRIBUTING.md) guidelines followed. +* [ ] Change log entry added, according to the guidelines in [When to add a changelog entry](https://github.com/open-telemetry/semantic-conventions/blob/main/CONTRIBUTING.md#when-to-add-a-changelog-entry). + * If your PR does not need a change log, start the PR title with `[chore]` +* [ ] [schema-next.yaml](https://github.com/open-telemetry/semantic-conventions/blob/main/schema-next.yaml) updated with changes to existing conventions. diff --git a/.github/auto_assign_issue.yml b/.github/auto_assign_issue.yml index 7a37146df5..82ebdb891d 100644 --- a/.github/auto_assign_issue.yml +++ b/.github/auto_assign_issue.yml @@ -6,7 +6,9 @@ addAssignees: true # A list of assignees, overrides reviewers if set assignees: + - AlexanderWert - arminru + - joaopgrassi - jsuereth - reyang diff --git a/.github/auto_assign_pr.yml b/.github/auto_assign_pr.yml index 6b9200b670..58d2db55b0 100644 --- a/.github/auto_assign_pr.yml +++ b/.github/auto_assign_pr.yml @@ -10,7 +10,9 @@ useAssigneeGroups: true # A list of assignees, split into different groups, to be added to pull requests (GitHub user name) assigneeGroups: maintainers: + - AlexanderWert - arminru + - joaopgrassi - jsuereth - reyang diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml new file mode 100644 index 0000000000..a5a390b69d --- /dev/null +++ b/.github/workflows/changelog.yml @@ -0,0 +1,88 @@ +# This action requires that any PR targeting the main branch should touch at +# least one CHANGELOG file. If a CHANGELOG entry is not required, add the "Skip +# Changelog" label to disable this action. + +name: 'Changelog' + +on: + pull_request: + types: [opened, ready_for_review, synchronize, reopened, labeled, unlabeled] + branches: + - main + +concurrency: + group: ${{ github.workflow }}-${{ github.head_ref }} + cancel-in-progress: true + +jobs: + changelog: + runs-on: ubuntu-latest + if: >- + ${{ + !contains(github.event.pull_request.labels.*.name, 'dependencies') && + !contains(github.event.pull_request.labels.*.name, 'Skip Changelog') && + !contains(github.event.pull_request.title, '[chore]') + }} + env: + PR_HEAD: ${{ github.event.pull_request.head.sha }} + steps: + - name: Checkout Repo + uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Setup Go + uses: actions/setup-go@v4 + with: + go-version: ~1.21.6 + - name: Cache Go + id: go-cache + uses: actions/cache@v3 + with: + path: | + ~/go/bin + ~/go/pkg/mod + key: changelog-${{ runner.os }}-go-${{ hashFiles('**/go.sum') }} + + - name: Ensure no changes to the CHANGELOG.md + run: | + if [[ $(git diff --name-only $(git merge-base origin/main $PR_HEAD) $PR_HEAD ./CHANGELOG*.md) ]] + then + echo "CHANGELOG.md should not be directly modified." + echo "Please add a .yaml file to the ./.chloggen/ directory." + echo "See CONTRIBUTING.md for more details." + echo "Alternately, add either \"[chore]\" to the title of the pull \ request or add the \"Skip Changelog\" label if this job should be skipped." + false + else + echo "CHANGELOG.md was not modified." + fi + + - name: Ensure ./.chloggen/*.yaml addition(s) + run: | + if [[ 1 -gt $(git diff --diff-filter=A --name-only $(git merge-base origin/main $PR_HEAD) $PR_HEAD ./.chloggen | grep -c \\.yaml) ]] + then + echo "No changelog entry was added to the ./.chloggen/ directory." + echo "Please add a .yaml file to the ./.chloggen/ directory." + echo "See CONTRIBUTING.md for more details." + echo "Alternately, add either \"[chore]\" to the title of the pull request or add the \"Skip Changelog\" label if this job should be skipped." + false + else + echo "A changelog entry was added to the ./.chloggen/ directory." + fi + + - name: Validate ./.chloggen/*.yaml changes + run: | + make chlog-validate \ + || { echo "New ./.chloggen/*.yaml file failed validation."; exit 1; } + + # In order to validate any links in the yaml file, render the config to markdown + - name: Render .chloggen changelog entries + run: make chlog-preview > changelog_preview.md + - name: Install markdown-link-check + run: npm install -g markdown-link-check + - name: Run markdown-link-check + run: | + markdown-link-check \ + --verbose \ + --config .markdown_link_check_config.json \ + changelog_preview.md \ + || { echo "Check that anchor links are lowercase"; exit 1; } diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index 4ae744dcbe..9c8907000d 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -2,9 +2,7 @@ name: Checks on: push: - branches: [ main ] pull_request: - branches: [ main ] jobs: markdownlint: @@ -81,10 +79,10 @@ jobs: dotnet-version: 6.0.x - name: install docfx - run: dotnet tool update -g docfx --version "3.0.0-*" --add-source https://docfx.pkgs.visualstudio.com/docfx/_packaging/docs-public-packages/nuget/v3/index.json + run: dotnet tool update -g docfx - name: run docfx - run: docfx build --dry-run + run: docfx build --dryRun semantic-conventions: runs-on: ubuntu-latest @@ -93,9 +91,25 @@ jobs: - name: verify semantic convention tables run: make table-check + semantic-conventions-compatibility: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - name: verify semantic convention compatibility with latest released version + run: make compatibility-check + schemas-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 - name: verify schemas run: make schema-check + + areas-dropdown-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - name: Components dropdown in issue templates + run: | + make generate-gh-issue-templates + git diff --exit-code '.github/ISSUE_TEMPLATE' || (echo 'Dropdowns in issue templates is out of date, please run "make generate-gh-issue-templates" and commit the changes in this PR. Please note, if you are running it on Mac OS X, please make sure to use GNU version of sed instead of default "sed".' && exit 1) diff --git a/.github/workflows/generate-registry-area-labels.yml b/.github/workflows/generate-registry-area-labels.yml new file mode 100644 index 0000000000..58f3b62b3a --- /dev/null +++ b/.github/workflows/generate-registry-area-labels.yml @@ -0,0 +1,24 @@ +name: 'Generate registry area labels' +on: + push: + branches: [main] + paths: + - model/registry/** + - ./.github/workflows/generate-registry-area-labels.yml + - ./.github/workflows/scripts/generate-registry-area-labels.sh + workflow_dispatch: + +jobs: + generate-component-labels: + runs-on: ubuntu-latest + if: ${{ github.repository_owner == 'open-telemetry' }} + steps: + - uses: actions/checkout@v4 + + - name: Run update permissions + run: chmod +x ./.github/workflows/scripts/generate-registry-area-labels.sh + + - name: Generate registry area labels + run: ./.github/workflows/scripts/generate-registry-area-labels.sh + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/prepare-new-issue.yml b/.github/workflows/prepare-new-issue.yml new file mode 100644 index 0000000000..345b7dcd1e --- /dev/null +++ b/.github/workflows/prepare-new-issue.yml @@ -0,0 +1,22 @@ +name: 'Prepare new issue' +on: + issues: + types: [opened] + +jobs: + prepare-new-issue: + runs-on: ubuntu-latest + if: ${{ github.repository_owner == 'open-telemetry' }} + steps: + - uses: actions/checkout@v4 + + - name: Run update permissions + run: chmod +x ./.github/workflows/scripts/prepare-new-issue.sh + + - name: Run prepare-new-issue.sh + run: ./.github/workflows/scripts/prepare-new-issue.sh + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + ISSUE: ${{ github.event.issue.number }} + BODY: ${{ github.event.issue.body }} + OPENER: ${{ github.event.issue.user.login }} diff --git a/.github/workflows/scripts/generate-registry-area-labels.sh b/.github/workflows/scripts/generate-registry-area-labels.sh new file mode 100755 index 0000000000..3a2af777e6 --- /dev/null +++ b/.github/workflows/scripts/generate-registry-area-labels.sh @@ -0,0 +1,33 @@ +#!/usr/bin/env bash +# +# Copyright The OpenTelemetry Authors +# SPDX-License-Identifier: Apache-2.0 +# +# Create labels for all semantic convention areas that are in model/registry. +# Existing labels are not affected. +# +# Note that there is a 50-character limit on labels, so some areas may +# not have a corresponding label. + +set -euo pipefail + +CUR_DIRECTORY=$(dirname "$0") +AREAS=$(sh "${CUR_DIRECTORY}/get-registry-areas.sh") + +echo -e "\nStarting to create area labels" +echo -e "--------------------------------\n" + +for AREA in ${AREAS}; do + LABEL_NAME=$(basename "${AREA}" .yaml) + + if (( "${#LABEL_NAME}" > 50 )); then + echo "'${LABEL_NAME}' exceeds GitHubs 50-character limit on labels, skipping" + continue + fi + echo "area:${LABEL_NAME}" + gh label create "area:${LABEL_NAME}" -c "#425cc7" --force +done + +echo -e "\nLabels created successfully" +echo -e "--------------------------------\n" + diff --git a/.github/workflows/scripts/get-registry-areas.sh b/.github/workflows/scripts/get-registry-areas.sh new file mode 100755 index 0000000000..b4fd8b6e18 --- /dev/null +++ b/.github/workflows/scripts/get-registry-areas.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash +# +# Copyright The OpenTelemetry Authors +# SPDX-License-Identifier: Apache-2.0 +# +# Get a list of the semantic conventions areas from the registry. + +CUR_DIRECTORY=$(dirname "$0") +REPO_DIR="$( cd "$CUR_DIRECTORY/../../../" && pwd )" +REGISTRY_DIR="$( cd "$REPO_DIR/model/registry" && pwd )" + + +for entry in $(ls $REGISTRY_DIR | egrep '\.yaml$' | sort) +do + echo "$entry" +done diff --git a/.github/workflows/scripts/prepare-new-issue.sh b/.github/workflows/scripts/prepare-new-issue.sh new file mode 100755 index 0000000000..c8af7d0b4a --- /dev/null +++ b/.github/workflows/scripts/prepare-new-issue.sh @@ -0,0 +1,62 @@ +#!/usr/bin/env bash +# +# Copyright The OpenTelemetry Authors +# SPDX-License-Identifier: Apache-2.0 +# +# + +# This script extracts the "Area" from the issue body and adds it as a label +# on newly created issues. The area from the issue body comes from +# the "Area" drop-down field in the ISSUE_TEMPLATE, which is auto-generated +# from the files inside model/registry. + +# TODO: This script can be later used to also auto-assign the correct code-owner +# once that is implemented. + +set -euo pipefail + +if [[ -z "${ISSUE:-}" || -z "${BODY:-}" || -z "${OPENER:-}" ]]; then + echo "Missing one of ISSUE, BODY, or OPENER, please ensure all are set." + exit 0 +fi + +LABELS="" +AREAS_SECTION_START=$( (echo "${BODY}" | grep -n '### Area(s)' | awk '{ print $1 }' | grep -oE '[0-9]+') || echo '-1' ) +BODY_AREAS="" + +if [[ "${AREAS_SECTION_START}" != '-1' ]]; then + BODY_AREAS=$(echo "${BODY}" | sed -n $((AREAS_SECTION_START+2))p) +fi + +for AREA in ${BODY_AREAS}; do + # Areas are delimited by ', ' and the for loop separates on spaces, so remove the extra comma. + AREA=${AREA//,/} + + if (( "${#AREA}" > 50 )); then + echo "'${AREA}' exceeds GitHub's 50-character limit on labels, skipping adding a label" + continue + fi + + if [[ -n "${LABELS}" ]]; then + LABELS+="," + fi + LABELS+="${AREA}" +done + +if [[ -v PINGED_AREAS[@] ]]; then + echo "The issue was associated with areas:" "${!PINGED_AREAS[@]}" +else + echo "No related areas were given" +fi + +if [[ -n "${LABELS}" ]]; then + # Notes on this call: + # 1. Labels will be deduplicated by the GitHub CLI. + # 2. The call to edit the issue will fail if any of the + # labels doesn't exist. We can be reasonably sure that + # all labels will exist since they come from a known set. + echo "Adding the following labels: ${LABELS//,/ /}" + gh issue edit "${ISSUE}" --add-label "${LABELS}" || true +else + echo "No labels were found to add" +fi diff --git a/.github/workflows/stale-pr.yml b/.github/workflows/stale-pr.yml new file mode 100644 index 0000000000..d5259a6140 --- /dev/null +++ b/.github/workflows/stale-pr.yml @@ -0,0 +1,22 @@ +name: "Close stale pull requests" +on: + schedule: + - cron: "12 3 * * *" # arbitrary time not to DDOS GitHub + +jobs: + stale: + runs-on: ubuntu-latest + steps: + - uses: actions/stale@v9 + with: + 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-draft-pr: true + # opt out of defaults to avoid marking issues as stale + days-before-stale: -1 + days-before-close: -1 + # overrides the above only for pull requests + days-before-pr-stale: 15 + days-before-pr-close: 7 diff --git a/.gitignore b/.gitignore index c9508b6a86..fdb9989733 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,7 @@ .project .settings bin +.vs # NetBeans /.nb-gradle diff --git a/.markdown_link_check_config.json b/.markdown_link_check_config.json index 368aba40aa..ede6fbc5eb 100644 --- a/.markdown_link_check_config.json +++ b/.markdown_link_check_config.json @@ -2,6 +2,9 @@ "ignorePatterns": [ { "pattern": "^https://github\\.com/open-telemetry/opentelemetry-specification/(issues|pull)" + }, + { + "pattern": "^https://github\\.com/open-telemetry/semantic-conventions/(issues|pull)" } ], "replacementPatterns": [ @@ -10,10 +13,11 @@ "replacement": "{{BASEURL}}/" }, { - "pattern": "^https://github.com/open-telemetry/semantic-conventions/(blob|tree)/[^/]+/docs/", + "pattern": "^https://github.com/open-telemetry/semantic-conventions/(blob|tree)/main/docs/", "replacement": "LINK-CHECK-ERROR-USE-LOCAL-PATH-TO-DOC-PAGE-NOT-EXTERNAL-URL/" } ], "retryOn429": true, + "timeout": "30s", "aliveStatusCodes": [200, 403] } diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 61e39a0a22..d68351b3e6 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -12,3 +12,4 @@ ol-prefix: style: ordered no-inline-html: false fenced-code-language: false +no-space-in-code: false diff --git a/.prettierignore b/.prettierignore index aa4edb3751..c7137972a9 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,8 +1,12 @@ /.github +/.chloggen # for the first iteration, we only reformat /docs/cloud* and will add the rest in individual PRs /docs/** !/docs/cloud* !/docs/cloud*/** +!/docs/attributes-registry* +!/docs/attributes-registry*/** /model /schemas +CHANGELOG.md \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json index c216d9b9ef..7741a3e1f5 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -10,8 +10,8 @@ "MD040": false, }, "yaml.schemas": { - "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.17.0/semantic-conventions/semconv.schema.json": [ - "semantic_conventions/**/*.yaml" + "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.24.0/semantic-conventions/semconv.schema.json": [ + "model/**/*.yaml" ] }, "json.schemaDownload.enable": true diff --git a/.yamllint b/.yamllint index 39c91cefa1..0e43f20a2a 100644 --- a/.yamllint +++ b/.yamllint @@ -1,5 +1,11 @@ extends: default +ignore-from-file: + - .gitignore + +ignore: | + node_modules/* + rules: document-start: disable octal-values: enable @@ -7,6 +13,8 @@ rules: allowed-values: ['true', 'false', 'on'] # 'on' for GH action trigger line-length: max: 200 + ignore: | + .github/* indentation: check-multi-line-strings: false indent-sequences: consistent diff --git a/CHANGELOG.md b/CHANGELOG.md index 800a0d08a3..7e1071d8e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,14 +1,403 @@ -# Changelog + -Please update changelog as part of any significant pull request. Place short -description of your change into "Unreleased" section. As part of release process -content of "Unreleased" section content will generate release notes for the -release. +# Changelog + ## Unreleased +### Breaking + +### Features + +### Fixes + +## v1.25.0 + +### 🛑 Breaking changes 🛑 + +- `messaging`: Remove `network.transport` and `network.type` attributes from messaging semantic conventions, clarify when `network.peer.address|port` should be populated. (#690, #698) +- `db`: Remove `network.transport` and `network.type` attributes from database semantic conventions, clarify when `network.peer.address|port` should be populated. (#690, #768) +- `messaging`: Introduce common `messaging.destination.partition.id` instead of `messaging.kafka.destination.partition` (#798) +- `host`: [resource/host] Change type of host.cpu.stepping to string (#664, #665) +- `system`: Rename `system.processes.*` namespace to `system.process.*`(#484) +- `k8s`, `container`: Depluralize labels for pod (`k8s.pod.labels.*`) and container (`container.labels.*`) resources (#625) +- `process`: Generate process metrics from YAML (#330): + - Rename `process.threads` to `process.thread.count` + - Rename `process.open_file_descriptors` to `process.open_file_descriptor.count` + - Rename attributes for `process.cpu.*` + - `state` to `process.cpu.state` + - Change attributes for `process.disk.io` + - Instead of `direction` use `disk.io.direction` from global registry + - Change attributes for `process.network.io` + - Instead of `direction` use `network.io.direction` from global registry + - Rename attributes for `process.context_switches` + - `type` to `process.context_switch_type` + - Rename attributes for `process.paging.faults` + - `type` to `process.paging.fault_type` + +### 🚩 Deprecations 🚩 + +- `db`: Deprecate `db.connection_string` attribute in favor of `server.address` and `server.port` (#724, #769) +- `db`: Deprecate `db.jdbc.driver_classname` attribute (#796) + +### 🚀 New components 🚀 + +- `file`: Add new file namespace (#732) + +### 💡 Enhancements 💡 + +- `messaging`: Add `messaging.rabbitmq.message.delivery_tag`` to the list of RabbitMQ specific tags (#433) +- `messaging`: Clarify producer span relationships for messaging semantic conventions (#509) +- `rpc`: Add link to specification for metrics defined by gRPC community. (#627) +- `messaging`: Add messaging semantic conventions for settlement spans (#621) +- `messaging`: Clarifies span names for Azure messaging systems and adds `messaging.servicebus.disposition_status attribute`. (#697) +- `messaging`: Add a "Process" spans and metrics for messaging (#657) +- `db`: Update Elasticsearch attributes to use db.instance.id instead of db.elasticsearch.node.name (#725) +- `db`: Merge DB connection-level and call-level attributes tables (#780) +- `dns`: Introduces common DNS lookup duration metric and attributes. (#404) +- `other`: Update build-tools version to 0.24.0 and make semantic conventions compatible with this version (add stability on enum members and deprecated attributes). (#807) +- `system`: Align `system.cpu.state`'s definition with this of `process.cpu.state`. (#563) +- `container`: Add new container metrics for `cpu`, `memory`, `disk` and `network` (#282, #72) +- `url`: Sensitive content provided in `url.full`, `url.path`, and `url.query` SHOULD be scrubbed when instrumentations can identify it. (#676) +- `metrics`: Clarify metric attributes should be namespaced. (#394) +- `events`: Add clarification that the body of an Event will live in the LogRecord body field. (#566) +- `http`: Add `http.request.size` and `http.response.size` attributes for the total number of bytes in http messages (#38, #84) +- `http`: Extracts common HTTP client metrics from .NET conventions. (#800) +- `resource`: Define a common algorithm for `service.instance.id`. (#312) +- `user-agent`: Update user_agent subfields wording to support it's usage for non-browser products with multiple names/versions (#680) +- `url`: Add remaining ECS fields to the url namespace (#496) +- `messaging`: Make `network.protocol.name` conditionally required for messaging (#644) +- `cloud`: Add `azure_container_apps` to `cloud.platform` semantic conventions (#615) +- `user_agent`: Add `user_agent.name` and `user_agent.version` attributes (#452) +- `messaging`: Add an example for gcp_pubsub asynchronous batch publish (#545) +- `aws`: Add `aws.ecs.task.id` attribute, corrected description for `aws.ecs.task.arn` (#597) +- `messaging`: Add Azure Service Bus and Event Hubs messaging attributes (#572) + +### 🧰 Bug fixes 🧰 + +- `aws-lambda`: Fix problem in `xray-lambda` propagator definition (#778) +- `http`: Two fixes to the HTTP semconv migration guide (#802) +- `network`: Clarifies that network.protocol.version represents negotiated version (#686) +- `jvm`: Fix JVM buffer metric schema translations (#683) + +## v1.24.0 (2023-12-15) + +### Breaking + +- Update `jvm.gc.duration` histogram buckets to `[ 0.01, 0.1, 1, 10 ]` + ([#317](https://github.com/open-telemetry/semantic-conventions/pull/317)) +- BREAKING: Change type of `host.cpu.model.id` and `host.cpu.model.family` to string. + ([#499](https://github.com/open-telemetry/semantic-conventions/pull/499)) +- Changed `messaging.system` attribute type to an open enum + ([#517](https://github.com/open-telemetry/semantic-conventions/pull/517)) +- Rename metrics `jvm.memory.usage` to `jvm.memory.used` and `jvm.memory.usage_after_last_gc` + to `jvm.memory.used_after_last_gc` + ([#536](https://github.com/open-telemetry/semantic-conventions/pull/536)) +- BREAKING: Change `event.name` definition to include `namespace` and remove `event.domain` from log event attributes. + ([#473](https://github.com/open-telemetry/semantic-conventions/pull/473)) +- BREAKING: Change `system.disk.io.direction` and `system.network.io.direction` + to global attributes `disk.io.direction` and `network.io.direction` + ([#530](https://github.com/open-telemetry/semantic-conventions/pull/530)) +- BREAKING: Change `messaging.kafka.partition` to `messaging.kafka.destination.partition` + ([#547](https://github.com/open-telemetry/semantic-conventions/pull/547)) + +### Features + +- Adds `labels` attribute to `k8s.pod` resource + ([#494](https://github.com/open-telemetry/semantic-conventions/pull/494)) +- Change Erlang managed thread attribute to be the Erlang process + ([#491](https://github.com/open-telemetry/semantic-conventions/pull/491)) +- Add gcp_pubsub as a messaging system + ([#490](https://github.com/open-telemetry/semantic-conventions/pull/490)) +- Adds `annotation` attribute to `k8s.pod` resource + ([#494](https://github.com/open-telemetry/semantic-conventions/pull/573)) +- Add `code.stacktrace` attribute + ([#435](https://github.com/open-telemetry/semantic-conventions/pull/435)) +- Add `http.flavor` and `http.user_agent` to list of deprecated attributes + ([#503](https://github.com/open-telemetry/semantic-conventions/pull/503)) +- Add Semantic conventions for TLS/SSL encrypted communication. + ([#21](https://github.com/open-telemetry/semantic-conventions/pull/21)) +- Add `messaging.gcp_pubsub.message.ordering_key` attribute. + ([#528](https://github.com/open-telemetry/semantic-conventions/pull/528)) +- Define how to set `process.runtime.name`, `process.runtime.version`, + `process.runtime.description` for .NET runtime. + ([#561](https://github.com/open-telemetry/semantic-conventions/pull/561)) +- Add `db.instance.id` attribute. + ([#345](https://github.com/open-telemetry/semantic-conventions/pull/345)) +- Add messaging metrics + ([#163](https://github.com/open-telemetry/semantic-conventions/pull/163)) +- Add .NET 8.0 metrics for HTTP client, ASP.NET Core, SignalR server and Kestrel. + ([#283](https://github.com/open-telemetry/semantic-conventions/pull/283)) +- Add system shared IO direction attributes + ([#530](https://github.com/open-telemetry/semantic-conventions/pull/530)) +- JVM metrics marked stable + ([#569](https://github.com/open-telemetry/semantic-conventions/pull/569)) +- Add attribute for k8s pod annotations + ([#573](https://github.com/open-telemetry/semantic-conventions/pull/573)) +- Replace AWS X-Ray Environment Span Link section with AWS X-Ray Active Tracing Considerations + ([#354](https://github.com/open-telemetry/semantic-conventions/pull/354)) + +### Fixes + +- Remove misleading pluralization wording related to count metrics + ([#488](https://github.com/open-telemetry/semantic-conventions/pull/488)) +- Remove no longer relevant Oct 1 mention from `OTEL_SEMCONV_STABILITY_OPT_IN` + ([#541](https://github.com/open-telemetry/semantic-conventions/pull/541)) +- Update stability definitions of HTTP client and server duration metrics to + be consistent with markdown. + ([#587](https://github.com/open-telemetry/semantic-conventions/pull/587)) +- Use `deprecated` property to mark attributes as deprecated instead of `stability` + ([#588](https://github.com/open-telemetry/semantic-conventions/pull/588)) + +## v1.23.1 (2023-11-17) + +### Breaking + +### Features + +### Fixes + +- [backport to 1.23.x] Temp fix for separation of resource and semantic attributes + ([#524](https://github.com/open-telemetry/semantic-conventions/pull/524)) via + ([#537](https://github.com/open-telemetry/semantic-conventions/pull/537)) + +## v1.23.0 (2023-11-03) + +This release marks the first where the core of HTTP semantic conventions have +stabilized. + +### Breaking + +- BREAKING: Rename http.resend_count to http.request.resend_count. + ([#374](https://github.com/open-telemetry/semantic-conventions/pull/374)) +- BREAKING: Change `network.protocol.name` from recommended to opt-in in HTTP semconv. + ([#398](https://github.com/open-telemetry/semantic-conventions/pull/398)) +- BREAKING: Define url.scheme in terms of logical operation in HTTP server semconv. + ([#376](https://github.com/open-telemetry/semantic-conventions/pull/376)) +- BREAKING: Change `network.transport` from recommended to opt-in in HTTP semconv. + ([#402](https://github.com/open-telemetry/semantic-conventions/pull/402)) +- BREAKING: Change `network.type` from recommended to opt-in in HTTP semconv. + ([#410](https://github.com/open-telemetry/semantic-conventions/pull/410)) +- BREAKING: Factor in `X-Forwarded-Host` / `Forwarded` when capturing `server.address` and `server.port`. + ([#411](https://github.com/open-telemetry/semantic-conventions/pull/411)) +- Remove `thread.daemon`, and introduce `jvm.thread.daemon` instead. + Introduce `jvm.thread.state` attribute and add it to `jvm.thread.count` metric. + ([#297](https://github.com/open-telemetry/semantic-conventions/pull/297)) +- Fix `server.port` to be not required when `server.address` is not set. + ([#429](https://github.com/open-telemetry/semantic-conventions/pull/429)) +- Use seconds as default duration for FaaS duration histograms + ([#384](https://github.com/open-telemetry/semantic-conventions/pull/384)) +- BREAKING: Remove `total` from list of well-known values of `system.memory.state` attribute. + ([#409](https://github.com/open-telemetry/semantic-conventions/pull/409)) +- Remove `url.path` default value. + ([#462](https://github.com/open-telemetry/semantic-conventions/pull/462)) +- Remove conditional requirement on `network.peer.address` and `network.peer.port` + ([#449](https://github.com/open-telemetry/semantic-conventions/pull/449)) +- Change `user_agent.original` from recommended to opt-in on HTTP client spans. + ([#468](https://github.com/open-telemetry/semantic-conventions/pull/468)) +- Change `http.request.body.size` and `http.response.body.size` + from recommended to opt-in. + ([#460](https://github.com/open-telemetry/semantic-conventions/pull/460)) +- Clarify that `client.port` is the port of whichever client was captured in `client.address`. + ([#471](https://github.com/open-telemetry/semantic-conventions/pull/471)) +- Change `client.port` from recommended to opt-in on HTTP server spans + ([#472](https://github.com/open-telemetry/semantic-conventions/pull/472)) +- BREAKING: Make `url.scheme` opt_in for HTTP client and remove default value for + `server.port` making it required on the client. + ([#459](https://github.com/open-telemetry/semantic-conventions/pull/459)) +- Make `client.address` sampling relevant on HTTP server spans. + ([#469](https://github.com/open-telemetry/semantic-conventions/pull/469)) +- Change `network.protocol.name` from opt-in to conditionally required. + ([#478](https://github.com/open-telemetry/semantic-conventions/pull/478)) +- Remove outdated `http.request.header.host` guidance + ([#479](https://github.com/open-telemetry/semantic-conventions/pull/479)) +- Change sampling relevant from `MUST` to `SHOULD` + ([#486](https://github.com/open-telemetry/semantic-conventions/pull/486)) +- Make `user_agent.original` and `http.request.header.*` sampling relevant + on HTTP server spans. + ([#467](https://github.com/open-telemetry/semantic-conventions/pull/467)) + +### Features + +- Adds `session.previous_id` to session.md + ([#348](https://github.com/open-telemetry/semantic-conventions/pull/348)) +- Metric namespaces SHOULD NOT be pluralized. + ([#267](https://github.com/open-telemetry/opentelemetry-specification/pull/267)) +- Add opt-in `system.memory.limit` metric. + ([#409](https://github.com/open-telemetry/semantic-conventions/pull/409)) +- Add `host.mac` resource attribute convention. + ([#340](https://github.com/open-telemetry/semantic-conventions/pull/340)) +- Mark HTTP semantic conventions as stable. + ([#377](https://github.com/open-telemetry/semantic-conventions/pull/377)) + +### Fixes + +- Clarify that `error.type` should be the fully-qualified exception class name + when it represents an exception type. + ([#387](https://github.com/open-telemetry/semantic-conventions/pull/387)) +- Add cardinality warning about two opt-in HTTP metric attributes + ([#401](https://github.com/open-telemetry/semantic-conventions/pull/401)) +- Change `server.port` from recommended to conditionally required on HTTP server semconv. + ([#399](https://github.com/open-telemetry/semantic-conventions/pull/399)) +- Add cardinality warning about two opt-in HTTP metric attributes to all HTTP metrics. + ([#412](https://github.com/open-telemetry/semantic-conventions/pull/412)) +- Remove outdated note about not recording HTTP `server.address` when only IP address available. + ([#413](https://github.com/open-telemetry/semantic-conventions/pull/413)) +- Clarify HTTP server definitions and `server.address|port` notes. + ([#423](https://github.com/open-telemetry/semantic-conventions/pull/423)) +- Change the precedence between `:authority` and `Host` headers when populating + `server.address` and `server.port` attributes. + ([#455](https://github.com/open-telemetry/semantic-conventions/pull/455)) +- Explain `deployment.environment` impact on service identity. ([#481](https://github.com/open-telemetry/semantic-conventions/pull/481)) + +## v1.22.0 (2023-10-12) + +- Remove experimental Kafka metrics ([#338](https://github.com/open-telemetry/semantic-conventions/pull/338)) +- Adds `session.id` and session.md to general docs and model + ([#215](https://github.com/open-telemetry/semantic-conventions/pull/215)) +- Add `container.labels.` attributes. + ([#125](https://github.com/open-telemetry/semantic-conventions/pull/125)) +- Add `cluster.name` and `node.name` attributes to Elasticsearch semantic conventions. + ([#285](https://github.com/open-telemetry/semantic-conventions/pull/285)) - Fix the unit of metric.process.runtime.jvm.system.cpu.load_1m to be {run_queue_item} ([#95](https://github.com/open-telemetry/semantic-conventions/pull/95)) +- Update `.count` metric naming convention so that it only applies to UpDownCounters, + and add that `.total` should not be used by either Counters or UpDownCounters + ([#107](https://github.com/open-telemetry/semantic-conventions/pull/107)) +- Add `oci.manifest.digest`, `container.image.repo_digests` attributes. Make `container.image.tag` array and in plural form. + ([#159](https://github.com/open-telemetry/semantic-conventions/pull/159)) +- BREAKING: Rename `http.client.duration` and `http.server.duration` metrics to + `http.client.request.duration` and `http.server.request.duration` respectively. + ([#224](https://github.com/open-telemetry/semantic-conventions/pull/224)) +- Update HTTP `network.protocol.version` examples to match HTTP RFCs. + ([#228](https://github.com/open-telemetry/semantic-conventions/pull/228)) +- Re-introduce namespace and attributes to describe the original destination messages were + published to (`messaging.destination_publish.*`). + ([#156](https://github.com/open-telemetry/semantic-conventions/pull/156)) +- Generate FaaS metric semantic conventions from YAML. + ([#88](https://github.com/open-telemetry/semantic-conventions/pull/88)) + The conventions cover metrics that are recorded by the FaaS itself and not by + clients invoking them. +- BREAKING: Rename all JVM metrics from `process.runtime.jvm.*` to `jvm.*` + ([#241](https://github.com/open-telemetry/semantic-conventions/pull/241)) +- BREAKING: Add namespaces to JVM metric attributes ([#20](https://github.com/open-telemetry/semantic-conventions/pull/20)). + - Rename attributes `type` to `jvm.memory.type`, `pool` to `jvm.memory.pool.name` + - Applies to metrics: + - `jvm.memory.usage` + - `jvm.memory.init` + - `jvm.memory.committed` + - `jvm.memory.limit` + - `jvm.memory.usage_after_last_gc` + - Rename attributes `gc` to `jvm.gc.name`, `action` to `jvm.gc.action` + - Applies to metrics: + - `jvm.gc.duration` + - Rename attribute `daemon` to `thread.daemon` + - Applies to metrics: + - `jvm.threads.count` + - Rename attribute `pool` to `jvm.buffer.pool.name` + - Applies to metrics: + - `jvm.buffer.usage` + - `jvm.buffer.limit` + - `jvm.buffer.count` +- Clarify that `http/dup` has higher precedence than `http` in case both values are present + in `OTEL_SEMCONV_STABILITY_OPT_IN` + ([#249](https://github.com/open-telemetry/semantic-conventions/pull/249)) +- Add `jvm.cpu.count` metric. + ([#52](https://github.com/open-telemetry/semantic-conventions/pull/52)) +- BREAKING: Rename metrics `jvm.buffer.usage` to `jvm.buffer.memory.usage` + and `jvm.buffer.limit` to `jvm.buffer.memory.limit`. + ([#253](https://github.com/open-telemetry/semantic-conventions/pull/253)) +- BREAKING: Rename `jvm.classes.current_loaded` metrics to `jvm.classes.count` + ([#60](https://github.com/open-telemetry/semantic-conventions/pull/60)) +- BREAKING: Remove pluralization from JVM metric namespaces. + ([#252](https://github.com/open-telemetry/semantic-conventions/pull/252)) +- Simplify HTTP metric briefs. + ([#276](https://github.com/open-telemetry/semantic-conventions/pull/276)) +- Add host cpu resource attributes. + ([#209](https://github.com/open-telemetry/semantic-conventions/pull/209)) +- Introduce `error.type` attribute and use it in HTTP conventions + ([#205](https://github.com/open-telemetry/semantic-conventions/pull/205)) +- BREAKING: Change HTTP span name when method is unknown (use `HTTP` instead of `_OTHER`) + ([#270](https://github.com/open-telemetry/semantic-conventions/pull/270)) +- Moved RPC streaming notes from metric brief section to notes section. + ([#275](https://github.com/open-telemetry/semantic-conventions/pull/275)) +- Updates `client.address` to allow domain names for consistency with `server.address`. + ([#302](https://github.com/open-telemetry/semantic-conventions/pull/302)) +- BREAKING: Generate System metrics semconv from YAML. + ([#89](https://github.com/open-telemetry/semantic-conventions/pull/89)) + - Rename attributes for `system.cpu.*` metrics: + - `state` to `system.cpu.state` + - `cpu` to `system.cpu.logical_number` + - Rename attributes for `system.memory.*` metrics: + - `state` to `system.memory.state` + - Rename attributes for `system.paging.*` metrics: + - `state` to `system.paging.state` + - `type` to `system.paging.type` + - `direction` to `system.paging.direction` + - Rename attributes for `system.disk.*` metrics: + - `device` to `system.device` + - `direction` to `system.disk.direction` + - Rename attributes for `system.filesystem.*` metrics: + - `device` to `system.device` + - `state` to `system.filesystem.state` + - `type` to `system.filesystem.type` + - `mode` to `system.filesystem.mode` + - `mountpoint` to `system.filesystem.mountpoint` + - Rename attributes for `system.network.*` metrics: + - `device` to `system.device` + - `direction` to `system.network.direction` + - `protocol` to `network.protocol` + - `state` to `system.network.state` + - Rename attributes for `system.processes.*` metrics: + - `status` to `system.processes.status` +- BREAKING: Rename `messaging.message.payload_size_bytes` to `messaging.message.body.size`, + remove `messaging.message.payload_compressed_size_bytes`. + ([#229](https://github.com/open-telemetry/semantic-conventions/pull/229)) +- Add `system.linux.memory.available` metric. + ([#323](https://github.com/open-telemetry/semantic-conventions/pull/323)) +- BREAKING: Rename `http.server.request.size` metric to `http.server.request.body.size` + and `http.server.response.size` metric to `http.server.response.body.size` + ([#247](https://github.com/open-telemetry/semantic-conventions/pull/247)) +- Move non-`network.*` attributes out of network.yaml. + ([#296](https://github.com/open-telemetry/semantic-conventions/pull/296)) +- Introducing Android `android.os.api_level` resource attribute. + ([#328](https://github.com/open-telemetry/semantic-conventions/pull/328)) +- Added `os.build_id` resource attribute. + ([#293](https://github.com/open-telemetry/semantic-conventions/pull/293)) +- BREAKING: Remove the zero bucket boundary from `http.server.request.duration` + and `http.client.request.duration`. + ([#318](https://github.com/open-telemetry/semantic-conventions/pull/318)) +- Encourage setting `network.transport` when reporting port numbers + ([#289](https://github.com/open-telemetry/semantic-conventions/pull/289)) +- BREAKING: Add `url.scheme` to `http.client.*` metrics + ([#357](https://github.com/open-telemetry/semantic-conventions/pull/357)) +- BREAKING: Remove `server.socket.address` from HTTP and RPC client metrics. + ([#350](https://github.com/open-telemetry/semantic-conventions/pull/350)) +- Improve network attribute briefs. + ([#352](https://github.com/open-telemetry/semantic-conventions/pull/352)) +- Document the difference between host and system metrics + ([#324](https://github.com/open-telemetry/semantic-conventions/pull/324)) +- BREAKING: Rename `telemetry.auto.version` resource attribute to `telemetry.distro.version` + and add `telemetry.distro.name` resource attribute + ([#178](https://github.com/open-telemetry/semantic-conventions/pull/178)) +- Add `system.cpu.frequency` metric. + ([#337](https://github.com/open-telemetry/semantic-conventions/pull/337)) +- Improve HTTP metric briefs. + ([#366](https://github.com/open-telemetry/semantic-conventions/pull/366)) +- Add `host.ip` resource attribute convention. + ([#203](https://github.com/open-telemetry/semantic-conventions/pull/203)) +- BREAKING: remove `-` to `_` normalization from http header and rpc metadata + attribute keys. + ([#369](https://github.com/open-telemetry/semantic-conventions/pull/369)) +- BREAKING: Rename/replace `(client|server).socket.(address|port)` attributes + with `network.(peer|local).(address|port)`. + ([#342](https://github.com/open-telemetry/semantic-conventions/pull/342)) +- Make `network.protocol.name|version` description consistent between HTTP + spans and metrics. + ([#367](https://github.com/open-telemetry/semantic-conventions/pull/367)) ## v1.21.0 (2023-07-13) @@ -114,6 +503,8 @@ Note: This is the first release of Semantic Conventions separate from the Specif ([#133](https://github.com/open-telemetry/semantic-conventions/pull/133)) - Add markdown file for url semantic conventions ([#174](https://github.com/open-telemetry/semantic-conventions/pull/174)) +- Add `system.cpu.physical.count` and `system.cpu.logical.count` metrics. + ([#99](https://github.com/open-telemetry/opentelemetry-specification/pull/99)) ## v1.20.0 (2023-04-07) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bc249e0823..b3e8f596ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,20 +6,66 @@ Before you start - see OpenTelemetry general [contributing](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md) requirements and recommendations. +
+Table of Contents + + + +- [Sign the CLA](#sign-the-cla) +- [How to Contribute](#how-to-contribute) + - [Prerequisites](#prerequisites) + - [1. Modify the YAML model](#1-modify-the-yaml-model) + - [Schema files](#schema-files) + - [2. Update the markdown files](#2-update-the-markdown-files) + - [Hugo frontmatter](#hugo-frontmatter) + - [3. Verify the changes before committing](#3-verify-the-changes-before-committing) + - [4. Changelog](#4-changelog) + - [When to add a Changelog Entry](#when-to-add-a-changelog-entry) + - [Examples](#examples) + - [Adding a Changelog Entry](#adding-a-changelog-entry) + - [5. Getting your PR merged](#5-getting-your-pr-merged) +- [Automation](#automation) + - [Consistency Checks](#consistency-checks) + - [Auto formatting](#auto-formatting) + - [Markdown style](#markdown-style) + - [Misspell check](#misspell-check) + - [Markdown link check](#markdown-link-check) + - [Version compatibility check](#version-compatibility-check) +- [Updating the referenced specification version](#updating-the-referenced-specification-version) +- [Making a Release](#making-a-release) +- [Merging existing ECS conventions](#merging-existing-ecs-conventions) + + + +
+ ## Sign the CLA Before you can contribute, you will need to sign the [Contributor License Agreement](https://identity.linuxfoundation.org/projects/cncf). -## TODO +## How to Contribute -We need to flesh out the rest of the contributing document for specifics on -semantic conventions. +When contributing to semantic conventions, it's important to understand a few +key, but non-obvious, aspects: -### Consistency Checks +- All attributes, metrics, etc. are formally defined in YAML files under + the `model/` directory. +- All descriptions, normative language are defined in the `docs/` directory. +- All changes to existing attributes, metrics, etc. MUST be allowed as + per our [stability guarantees][stability guarantees] and + defined in a schema file. As part of any contribution, you should + include attribute changes defined in the `schema-next.yaml` file. +- Links to the specification repository MUST point to a tag and **not** to the `main` branch. + The tag version MUST match with the one defined in [README](README.md). -The Specification has a number of tools it uses to check things like style, -spelling and link validity. Before using the tools: +Please make sure all Pull Requests are compliant with these rules! + +### Prerequisites + +The Specification uses several tools to check things like style, +spelling and link validity. Before contributing, make sure to have your +environment configured: - Install the latest LTS release of **[Node](https://nodejs.org/)**. For example, using **[nvm][]** under Linux run: @@ -28,35 +74,166 @@ spelling and link validity. Before using the tools: nvm install --lts ``` -- Install tooling packages: +- Then from the root of the project, install the tooling packages: ```bash npm install ``` -You can perform all checks locally using this command: +### 1. Modify the YAML model + +Refer to the +[Semantic Convention YAML Language](https://github.com/open-telemetry/build-tools/blob/v0.24.0/semantic-conventions/syntax.md) +to learn how to make changes to the YAML files. + +#### Schema files + +When making changes to existing semantic conventions (attributes, metrics, etc) +you MUST also update the `schema-next.yaml` file with the changes. + +For details, please read +[the schema specification](https://opentelemetry.io/docs/specs/otel/schemas/). + +You can also take examples from past changes inside the `schemas` folder. + +> [!WARNING] +> DO NOT add your changes to files inside the `schemas` folder. Always add your +> changes to the `schema-next.yaml` file. + +### 2. Update the markdown files + +After updating the YAML file(s), you need to update +the respective markdown files. For this, run the following commands: + +```bash +make table-generation attribute-registry-generation +``` + +#### Hugo frontmatter + +At the top of all Markdown files under the `docs/` directory, you will see +headers like the following: + +```md + +``` + +When creating new markdown files, you should provide the `linkTitle` attribute. +This is used to generate the navigation bar on the website, +and will be listed relative to the "parent" document. + +### 3. Verify the changes before committing + +Before sending a PR with your changes, make sure to run the automated checks: ```bash make check ``` -Note: This can take a long time as it checks all links. You should use this -prior to submitting a PR to ensure validity. However, you can run individual -checks directly. +Alternatively, you can run each check individually. +Refer to the [Automation](#automation) section for more details. -See: +### 4. Changelog -- [MarkdownStyle](#markdown-style) -- [Misspell Check](#misspell-check) -- Markdown link checking (docs TODO) -- Prettier formatting +#### When to add a Changelog Entry + +Pull requests that contain user-facing changes will require a changelog entry. +Keep in mind the following types of users (not limited to): + +1. Those who are consuming the data following these conventions (e.g., in alerts, dashboards, queries) +2. Those who are using the conventions in instrumentations (e.g., library authors) +3. Those who are using the conventions to derive heuristics, predictions and automatic analyses (e.g., observability products/back-ends) + +If a changelog entry is not required (e.g. editorial or trivial changes), +a maintainer or approver will add the `Skip Changelog` label to the pull request. + +##### Examples + +Changelog entry required: + +- Any modification to existing conventions with change in functionality/behavior +- New semantic conventions +- Changes on definitions, normative language (in `/docs`) + +No changelog entry: + +- Typical documentation/editorial updates (e.g. grammar fixes, restructuring) +- Changes in internal tooling (e.g. make file, GH actions, etc) +- Refactorings with no meaningful change in functionality +- Chores, such as enabling linters, updating dependencies + +#### Adding a Changelog Entry -### YAML to Markdown +The [CHANGELOG.md](./CHANGELOG.md) files in this repo is autogenerated +from `.yaml` files in the [/.chloggen](/.chloggen) directory. -Semantic conventions are declared in YAML files and markdown tables are -generated from these files. Read about semantic convention updates [here](./model/README.md). +Your pull request should add a new `.yaml` file to this directory. +The name of your file can be arbitrary but must be unique since the last release. -### Autoformatting +During the release process, all `./.chloggen/*.yaml` files are transcribed into +`CHANGELOG.md` and then deleted. + +1. Create an entry file using `make chlog-new`. The command generates a new file, + with its name based on the current branch (e.g. `./.chloggen/my-feature-xyz.yaml`) +2. Fill in all the fields in the generated file +3. The value for the `component` field MUST match a filename (without type) in the + [registry](https://github.com/open-telemetry/semantic-conventions/tree/main/model/registry) + (e.g. `browser`, `http`) +4. Run `make chlog-validate` to ensure the new file is valid +5. Commit and push the file + +Alternately, copy `./.chloggen/TEMPLATE.yaml`, or just create your file from scratch. + +### 5. Getting your PR merged + +A PR (pull request) is considered to be **ready to merge** when: + +- It has received at least two approvals from the [code + owners](./.github/CODEOWNERS) (if approvals are from only one company, they + won't count) +- There is no `request changes` from the [code owners](./.github/CODEOWNERS) +- There is no open discussions +- It has been at least two working days since the last modification (except for + the trivial updates, such like typo, cosmetic, rebase, etc.). This gives + people reasonable time to review +- Trivial changes (typos, cosmetic changes, CI improvements, etc.) don't have to + wait for two days + +Any [maintainer](./README.md#contributing) can merge the PR once it is **ready +to merge**. + +## Automation + +Semantic Conventions provides a set of automated tools for general development. + +### Consistency Checks + +The Specification has a number of tools it uses to check things like style, +spelling and link validity. + +You can perform all checks locally using this command: + +```bash +make check +``` + +> Note: `make check` can take a long time as it checks all links. +> You should use this prior to submitting a PR to ensure validity. +> However, you can run individual checks directly. + +For more information on each check, see: + +- [Markdown style](#markdown-style) +- [Misspell check](#misspell-check) +- [Markdown link check](#markdown-link-check) +- Prettier formatting + +### Auto formatting Semantic conventions have some autogenerated components and additionally can do automatic style/spell correction. You can run all of this via: @@ -70,7 +247,7 @@ You can also run these fixes individually. See: - [Misspell Correction](#misspell-check) -- Table Generation (docs TODO) +- [Update the markdown files](#2-update-the-markdown-files) ### Markdown style @@ -116,6 +293,26 @@ To quickly fix typos, use make misspell-correction ``` +### Markdown link check + +To check the validity of links in all markdown files, run the following command: + +```bash +make markdown-link-check +``` + +### Version compatibility check + +Semantic conventions are validated for backward compatibility with last released versions. Here's [the full list of compatibility checks](https://github.com/open-telemetry/build-tools/blob/main/semantic-conventions/README.md#version-compatibility-check). +Removing attributes, metrics, or enum members is not allowed, they should be deprecated instead. +It applies to stable and experimental conventions and prevents semantic conventions auto-generated libraries from introducing breaking changes. + +You can run backward compatibility check in all yaml files with the following command: + +```bash +make compatibility-check +``` + ## Updating the referenced specification version 1. Open the `./internal/tools/update_specification_version.sh` script. @@ -134,9 +331,39 @@ make misspell-correction - Ensure the `next` version is appropriately configured as the `{version}`. - Copy `schema-next.yaml` to `schemas/{version}`. - Add `next` as a version in `schema-next.yaml` version. - - Update `CHANGELOG.md` for the latest version. - - Add `## v{version} ({date})` under `## Unreleased` - - Send staging tag as PR for review. -- Create a tag `v{version}` on the merged PR and push remote. + - Run `make chlog-update VERSION=v{version}` + - `make chlog-update` will clean up all the current `.yaml` files inside the + `.chloggen` folder automatically + - Double check that `CHANGELOG.md` is updated with the proper `v{version}` + - Send staging branch as PR for review. +- After the release PR is merged, create a [new release](https://github.com/open-telemetry/semantic-conventions/releases/new): + - Set title and tag to `v{version}` + - Set target to the commit of the merged release PR + - Copy changelog to the release notes + - Verify that the release looks like expected + - Publish release + +New release is then auto-discovered by [opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) pipelines which (via bot-generated PR) +eventually results in new version of schema file being published. + +## Merging existing ECS conventions + +The Elastic Common Schema (ECS) is being merged into OpenTelemetry Semantic +Conventions per [OTEP 222][otep222]. When adding a semantic convention that +exists in some form in ECS, consider the following guidelines: + +- Prefer using the existing ECS name when possible. In particular: + - If proposing a name that differs from the ECS convention, provide usage + data, user issue reports, feature requests, examples of prior work on a + different standard or comparable evidence about the alternatives. + - When no suitable alternatives are provided, altering an ECS name solely + for the purpose of complying with [Name Pluralization guidelines](docs/general/attribute-naming.md#name-pluralization-guidelines) + MAY BE avoided. +- Do not use an existing ECS name as a namespace. If the name must differ, use a + different namespace name to avoid clashes or avoid using the namespace + entirely. See the [ECS field reference] for existing namespaces. [nvm]: https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating +[stability guarantees]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.26.0/specification/versioning-and-stability.md#semantic-conventions-stability +[otep222]: https://github.com/open-telemetry/oteps/pull/222 +[ECS field reference]: https://www.elastic.co/guide/en/ecs/current/ecs-field-reference.html diff --git a/Makefile b/Makefile index 4d04b73d8f..fb099e9d45 100644 --- a/Makefile +++ b/Makefile @@ -3,16 +3,22 @@ ALL_DOCS := $(shell find . -type f -name '*.md' -not -path './.github/*' -not -p PWD := $(shell pwd) TOOLS_DIR := ./internal/tools + MISSPELL_BINARY=bin/misspell MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY) +CHLOGGEN_BINARY=bin/chloggen +CHLOGGEN = $(TOOLS_DIR)/$(CHLOGGEN_BINARY) +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.19.0 +SEMCONVGEN_VERSION=0.24.0 +WEAVER_VERSION=latest # TODO: add `yamllint` step to `all` after making sure it works on Mac. .PHONY: all -all: install-tools markdownlint markdown-link-check misspell table-check schema-check \ +all: install-tools markdownlint markdown-link-check misspell table-check compatibility-check schema-check \ check-file-and-folder-names-in-docs .PHONY: check-file-and-folder-names-in-docs @@ -57,7 +63,7 @@ markdown-toc: @for f in $(ALL_DOCS); do \ if grep -q '' $$f; then \ echo markdown-toc: processing $$f; \ - npx --no -- markdown-toc --no-first-h1 --no-stripHeadingTags -i $$f || exit 1; \ + npx --no -- markdown-toc --bullets "-" --no-first-h1 --no-stripHeadingTags -i $$f || exit 1; \ else \ echo markdown-toc: no TOC markers, skipping $$f; \ fi; \ @@ -90,13 +96,37 @@ yamllint: .PHONY: table-generation table-generation: docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec \ - otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec + otel/weaver:${WEAVER_VERSION} registry update-markdown \ + --registry=/source \ + --attribute-registry-base-url="/docs/attributes-registry" \ + /spec + +# Generate attribute registry markdown. +.PHONY: attribute-registry-generation +attribute-registry-generation: + docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec -v $(PWD)/templates:/weaver/templates \ + otel/weaver:${WEAVER_VERSION} registry generate \ + --registry=/source \ + --templates=/weaver/templates \ + markdown \ + /spec/attributes-registry/ + npm run fix:format -# Check if current markdown tables differ from the ones that would be generated from YAML definitions +# Check if current markdown tables differ from the ones that would be generated from YAML definitions (weaver). .PHONY: table-check table-check: docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec \ - otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec --md-check + otel/weaver:${WEAVER_VERSION} registry update-markdown \ + --registry=/source \ + --attribute-registry-base-url="/docs/attributes-registry" \ + --dry-run \ + /spec + +LATEST_RELEASED_SEMCONV_VERSION := $(shell git describe --tags --abbrev=0 | sed 's/v//g') +.PHONY: compatibility-check +compatibility-check: + docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec \ + otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source compatibility --previous-version $(LATEST_RELEASED_SEMCONV_VERSION) .PHONY: schema-check schema-check: @@ -111,16 +141,44 @@ fix-format: npm run fix:format # Run all checks in order of speed / likely failure. +# As a last thing, run attribute registry generation and git-diff for differences. .PHONY: check -check: misspell markdownlint markdown-link-check check-format +check: misspell markdownlint check-format markdown-toc compatibility-check markdown-link-check attribute-registry-generation + git diff --exit-code ':*.md' || (echo 'Generated markdown Table of Contents is out of date, please run "make markdown-toc" and commit the changes in this PR.' && exit 1) @echo "All checks complete" # Attempt to fix issues / regenerate tables. .PHONY: fix -fix: table-generation misspell-correction fix-format +fix: table-generation attribute-registry-generation misspell-correction fix-format markdown-toc @echo "All autofixes complete" .PHONY: install-tools install-tools: $(MISSPELL) npm install @echo "All tools installed" + +$(CHLOGGEN): + cd $(TOOLS_DIR) && go build -o $(CHLOGGEN_BINARY) go.opentelemetry.io/build-tools/chloggen + +FILENAME?=$(shell git branch --show-current) +.PHONY: chlog-new +chlog-new: $(CHLOGGEN) + $(CHLOGGEN) new --config $(CHLOGGEN_CONFIG) --filename $(FILENAME) + +.PHONY: chlog-validate +chlog-validate: $(CHLOGGEN) + $(CHLOGGEN) validate --config $(CHLOGGEN_CONFIG) + +.PHONY: chlog-preview +chlog-preview: $(CHLOGGEN) + $(CHLOGGEN) update --config $(CHLOGGEN_CONFIG) --dry + +.PHONY: chlog-update +chlog-update: $(CHLOGGEN) + $(CHLOGGEN) update --config $(CHLOGGEN_CONFIG) --version $(VERSION) + +# Updates the areas (registry yaml file names) on all ISSUE_TEMPLATE +# files that have the "area" dropdown field +.PHONY: generate-gh-issue-templates +generate-gh-issue-templates: + $(TOOLS_DIR)/scripts/update-issue-template-areas.sh diff --git a/README.md b/README.md index d568e1955d..0dad278343 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,16 @@ -# OpenTelemetry Semantic Conventions +# OpenTelemetry Icon OpenTelemetry Semantic Conventions -Welcome to the new repository! +[![Checks](https://github.com/open-telemetry/semantic-conventions/workflows/Checks/badge.svg?branch=main)](https://github.com/open-telemetry/semantic-conventions/actions?query=workflow%3A%22Checks%22+branch%3Amain) +[![GitHub tag (latest SemVer)](https://img.shields.io/github/tag/open-telemetry/semantic-conventions.svg?logo=opentelemetry&&color=f5a800&label=Latest%20release)](https://github.com/open-telemetry/semantic-conventions/releases/latest) +[![Specification Version](https://img.shields.io/badge/OTel_specification_version-v1.31.0-blue?logo=opentelemetry&color=f5a800)](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.31.0) -This is currently a direct copy/filter-branch of the Specification repository -with only semantic conventions included. - -This repository is currently using [this specification version][SpecificationVersion]. +Semantic Conventions define a common set of (semantic) attributes which +provide meaning to data when collecting, producing and consuming it. ## Read the docs -The documentation currently resides in the [doc](docs/README.md) folder. +The human-readable version of the semantic conventions resides in the [docs](docs/README.md) folder. +Major parts of these Markdown documents are generated from the YAML definitions located in the [model](model/README.md) folder. ## Contributing @@ -17,11 +18,9 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) Approvers ([@open-telemetry/specs-semconv-approvers](https://github.com/orgs/open-telemetry/teams/specs-semconv-approvers)): +- [Alexandra Konrad](https://github.com/trisch-me), Elastic - [Christian Neumüller](https://github.com/Oberon00), Dynatrace - [James Moessis](https://github.com/jamesmoessis), Atlassian -- [Joao Grassi](https://github.com/joaopgrassi), Dynatrace -- [Johannes Tax](https://github.com/pyohannes), Microsoft -- [Liudmila Molkova](https://github.com/lmolkova), Microsoft - [Sean Marciniak](https://github.com/MovieStoreGuy), Atlassian - [Ted Young](https://github.com/tedsuo), Lightstep @@ -29,10 +28,12 @@ _Find more about the approver role in [community repository](https://github.com/ Maintainers ([@open-telemetry/specs-semconv-maintainers](https://github.com/orgs/open-telemetry/teams/specs-semconv-maintainers)): -- [Josh Suereth](https://github.com/jsuereth) -- [Armin Ruech](https://github.com/arminru) -- [Reiley Yang](https://github.com/reyang) +- [Alexander Wert](https://github.com/AlexanderWert), Elastic +- [Armin Ruech](https://github.com/arminru), Dynatrace +- [Joao Grassi](https://github.com/joaopgrassi), Dynatrace +- [Johannes Tax](https://github.com/pyohannes), Grafana Labs +- [Josh Suereth](https://github.com/jsuereth), Google +- [Liudmila Molkova](https://github.com/lmolkova), Microsoft +- [Reiley Yang](https://github.com/reyang), Microsoft _Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer)._ - -[SpecificationVersion]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0 diff --git a/docfx.json b/docfx.json index f69395082c..a04e6403f4 100644 --- a/docfx.json +++ b/docfx.json @@ -2,6 +2,6 @@ "files": "**/*.{md,png}", "warningsAsErrors": true, "rules": { - "link-out-of-scope": "off" + "link-out-of-scope": "verbose" } } diff --git a/docs/README.md b/docs/README.md index 498f5e739c..27c2c200a0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,10 +5,10 @@ cascade: body_class: otel-docs-spec github_repo: &repo https://github.com/open-telemetry/semantic-conventions github_subdir: docs - path_base_for_github_subdir: content/en/docs/specs/semconv/ + path_base_for_github_subdir: tmp/semconv/docs/ github_project_repo: *repo path_base_for_github_subdir: - from: content/en/docs/specs/semconv/_index.md + from: tmp/semconv/docs/_index.md to: README.md ---> @@ -27,6 +27,8 @@ Semantic Conventions are defined for the following areas: * [Exceptions](exceptions/README.md): Semantic Conventions for exceptions. * [FaaS](faas/README.md): Semantic Conventions for Function as a Service (FaaS) operations. * [Feature Flags](feature-flags/README.md): Semantic Conventions for feature flag evaluations. +* [Generative AI](gen-ai/README.md): Semantic Conventions for generative AI (LLM, etc.) operations. +* [GraphQL](graphql/graphql-spans.md): Semantic Conventions for GraphQL implementations. * [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations. * [Messaging](messaging/README.md): Semantic Conventions for messaging operations and systems. * [Object Stores](object-stores/README.md): Semantic Conventions for object stores operations. diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md new file mode 100644 index 0000000000..66f750c036 --- /dev/null +++ b/docs/attributes-registry/README.md @@ -0,0 +1,88 @@ + + + + + +# Attribute Registry + +The attributes registry is the place where attributes are defined. An attribute definition covers the following properties of an attribute: + +- the `id` (the fully qualified name) of the attribute +- the `type` of the attribute +- the `stability` of the attribute +- a `brief` description of the attribute and optionally a longer `note` +- example values + +Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id` and `type` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context. + +A definition of an attribute in the registry doesn't necessarily imply that the attribute is used in any of the semantic conventions. + +If applicable, application developers are encouraged to use existing attributes from this registry. See also [these recommendations][developers recommendations] regarding attribute selection and attribute naming for custom use cases. + +All registered attributes are listed by namespace in this registry. + +> **Warning** +> The following registry overview is a work in progress. +> +> Further attribute namespaces are currently being migrated and will appear in this registry soon. + +Currently, the following namespaces exist: + +- [Android](android.md) +- [Aspnetcore](aspnetcore.md) +- [AWS](aws.md) +- [Browser](browser.md) +- [Client](client.md) +- [Cloud](cloud.md) +- [CloudEvents](cloudevents.md) +- [Code](code.md) +- [Container](container.md) +- [Db](db.md) +- [Deployment](deployment.md) +- [Destination](destination.md) +- [Device](device.md) +- [Disk](disk.md) +- [Dns](dns.md) +- [Enduser](enduser.md) +- [Error](error.md) +- [Event](event.md) +- [Exception](exception.md) +- [Faas](faas.md) +- [Feature Flag](feature-flag.md) +- [File](file.md) +- [GCP](gcp.md) +- [Gen AI](gen-ai.md) +- [GraphQL](graphql.md) +- [Heroku](heroku.md) +- [Host](host.md) +- [HTTP](http.md) +- [iOS](ios.md) +- [JVM](jvm.md) +- [K8s](k8s.md) +- [Log](log.md) +- [Messaging](messaging.md) +- [Network](network.md) +- [OCI](oci.md) +- [OpenTracing](opentracing.md) +- [OS](os.md) +- [OTel](otel.md) +- [Peer](peer.md) +- [Process](process.md) +- [RPC](rpc.md) +- [Server](server.md) +- [Service](service.md) +- [Session](session.md) +- [SignalR](signalr.md) +- [Source](source.md) +- [System](system.md) +- [Telemetry](telemetry.md) +- [Thread](thread.md) +- [TLS](tls.md) +- [URL](url.md) +- [User Agent](user-agent.md) +- [Webengine](webengine.md) + +[developers recommendations]: ../general/attribute-naming.md#recommendations-for-application-developers diff --git a/docs/attributes-registry/android.md b/docs/attributes-registry/android.md new file mode 100644 index 0000000000..2e93f84293 --- /dev/null +++ b/docs/attributes-registry/android.md @@ -0,0 +1,36 @@ + + + + + +# Android + +- [Android](#android-attributes) +- [Android Deprecated](#android-deprecated-attributes) + +## Android Attributes + +The Android platform on which the Android application is running. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------- | +| `android.os.api_level` | string | Uniquely identifies the framework API revision offered by a version (`os.version`) of the android operating system. More information can be found [here](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels). | `33`; `32` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Android Deprecated Attributes + +This document defines attributes that represents an occurrence of a lifecycle transition on the Android platform. + +| Attribute | Type | Description | Examples | Stability | +| --------------- | ------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------- | +| `android.state` | string | Deprecated use the `device.app.lifecycle` event definition including `android.state` as a payload field instead. [1] | `created`; `background`; `foreground` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived. + +`android.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `created` | Any time before Activity.onResume() or, if the app has no Activity, Context.startService() has been called in the app for the first time. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `background` | Any time after Activity.onPause() or, if the app has no Activity, Context.stopService() has been called when the app was in the foreground state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `foreground` | Any time after Activity.onResume() or, if the app has no Activity, Context.startService() has been called when the app was in either the created or background states. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/aspnetcore.md b/docs/attributes-registry/aspnetcore.md new file mode 100644 index 0000000000..cde54126ba --- /dev/null +++ b/docs/attributes-registry/aspnetcore.md @@ -0,0 +1,46 @@ + + + + + +# Aspnetcore + +## Aspnetcore Attributes + +ASP.NET Core attributes + +| Attribute | Type | Description | Examples | Stability | +| ----------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------- | +| `aspnetcore.diagnostics.exception.result` | string | ASP.NET Core exception middleware handling result | `handled`; `unhandled`; `skipped` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `aspnetcore.diagnostics.handler.type` | string | Full type name of the [`IExceptionHandler`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.diagnostics.iexceptionhandler) implementation that handled the exception. | `Contoso.MyHandler` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `aspnetcore.rate_limiting.result` | string | Rate-limiting result, shows whether the lease was acquired or contains a rejection reason | `acquired`; `endpoint_limiter`; `global_limiter` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `aspnetcore.request.is_unhandled` | boolean | Flag indicating if request was handled by the application pipeline. | `true` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `aspnetcore.routing.is_fallback` | boolean | A value that indicates whether the matched route is a fallback route. | `true` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `aspnetcore.routing.match_status` | string | Match result - success or failure | `success`; `failure` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`aspnetcore.diagnostics.exception.result` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ----------- | ---------------------------------------------------------------- | ---------------------------------------------------------- | +| `handled` | Exception was handled by the exception handling middleware. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unhandled` | Exception was not handled by the exception handling middleware. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `skipped` | Exception handling was skipped because the response had started. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `aborted` | Exception handling didn't run because the request was aborted. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`aspnetcore.rate_limiting.result` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------------------ | -------------------------------------------------- | ---------------------------------------------------------- | +| `acquired` | Lease was acquired | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `endpoint_limiter` | Lease request was rejected by the endpoint limiter | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `global_limiter` | Lease request was rejected by the global limiter | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `request_canceled` | Lease request was canceled | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`aspnetcore.routing.match_status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --------- | --------------- | ---------------------------------------------------------- | +| `success` | Match succeeded | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `failure` | Match failed | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/attributes-registry/aws.md b/docs/attributes-registry/aws.md new file mode 100644 index 0000000000..1d8cac0f66 --- /dev/null +++ b/docs/attributes-registry/aws.md @@ -0,0 +1,167 @@ + + + + + +# AWS + +- [Aws](#aws-attributes) +- [Aws Dynamodb](#aws-dynamodb-attributes) +- [Aws Ecs](#aws-ecs-attributes) +- [Aws Eks](#aws-eks-attributes) +- [Aws Lambda](#aws-lambda-attributes) +- [Aws Log](#aws-log-attributes) +- [Aws S3](#aws-s3-attributes) + +## Aws Attributes + +This document defines generic attributes for AWS services. + +| Attribute | Type | Description | Examples | Stability | +| ---------------- | ------ | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------- | +| `aws.request_id` | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Aws Dynamodb Attributes + +This document defines attributes for AWS DynamoDB. + +| Attribute | Type | Description | Examples | Stability | +| --------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `aws.dynamodb.attribute_definitions` | string[] | The JSON-serialized value of each item in the `AttributeDefinitions` request field. | `{ "AttributeName": "string", "AttributeType": "string" }` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.attributes_to_get` | string[] | The value of the `AttributesToGet` request parameter. | `lives`; `id` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.consistent_read` | boolean | The value of the `ConsistentRead` request parameter. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.count` | int | The value of the `Count` response parameter. | `10` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.exclusive_start_table` | string | The value of the `ExclusiveStartTableName` request parameter. | `Users`; `CatsTable` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.global_secondary_index_updates` | string[] | The JSON-serialized value of each item in the `GlobalSecondaryIndexUpdates` request field. | `{ "Create": { "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.global_secondary_indexes` | string[] | The JSON-serialized value of each item of the `GlobalSecondaryIndexes` request field | `{ "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.index_name` | string | The value of the `IndexName` request parameter. | `name_to_group` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.limit` | int | The value of the `Limit` request parameter. | `10` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.local_secondary_indexes` | string[] | The JSON-serialized value of each item of the `LocalSecondaryIndexes` request field. | `{ "IndexArn": "string", "IndexName": "string", "IndexSizeBytes": number, "ItemCount": number, "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" } }` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.projection` | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.provisioned_read_capacity` | double | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. | `1.0`; `2.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.provisioned_write_capacity` | double | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. | `1.0`; `2.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.scan_forward` | boolean | The value of the `ScanIndexForward` request parameter. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.scanned_count` | int | The value of the `ScannedCount` response parameter. | `50` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.segment` | int | The value of the `Segment` request parameter. | `10` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.select` | string | The value of the `Select` request parameter. | `ALL_ATTRIBUTES`; `COUNT` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.table_count` | int | The number of items in the `TableNames` response parameter. | `20` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.table_names` | string[] | The keys in the `RequestItems` object field. | `Users`; `Cats` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.dynamodb.total_segments` | int | The value of the `TotalSegments` request parameter. | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Aws Ecs Attributes + +This document defines attributes for AWS Elastic Container Service (ECS). + +| Attribute | Type | Description | Examples | Stability | +| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `aws.ecs.cluster.arn` | string | The ARN of an [ECS cluster](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/clusters.html). | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.ecs.container.arn` | string | The Amazon Resource Name (ARN) of an [ECS container instance](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html). | `arn:aws:ecs:us-west-1:123456789123:container/32624152-9086-4f0e-acae-1a75b14fe4d9` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.ecs.launchtype` | string | The [launch type](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_types.html) for an ECS task. | `ec2`; `fargate` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.ecs.task.arn` | string | The ARN of a running [ECS task](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-account-settings.html#ecs-resource-ids). | `arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b`; `arn:aws:ecs:us-west-1:123456789123:task/my-cluster/task-id/23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.ecs.task.family` | string | The family name of the [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) used to create the ECS task. | `opentelemetry-family` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.ecs.task.id` | string | The ID of a running ECS task. The ID MUST be extracted from `task.arn`. | `10838bed-421f-43ef-870a-f43feacbbb5b`; `23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.ecs.task.revision` | string | The revision for the task definition used to create the ECS task. | `8`; `26` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`aws.ecs.launchtype` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --------- | ----------- | ---------------------------------------------------------------- | +| `ec2` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `fargate` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Aws Eks Attributes + +This document defines attributes for AWS Elastic Kubernetes Service (EKS). + +| Attribute | Type | Description | Examples | Stability | +| --------------------- | ------ | -------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------- | +| `aws.eks.cluster.arn` | string | The ARN of an EKS cluster. | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Aws Lambda Attributes + +This document defines attributes for AWS Lambda. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------- | +| `aws.lambda.invoked_arn` | string | The full invoked ARN as provided on the `Context` passed to the function (`Lambda-Runtime-Invoked-Function-Arn` header on the `/runtime/invocation/next` applicable). [1] | `arn:aws:lambda:us-east-1:123456:function:myfunction:myalias` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This may be different from `cloud.resource_id` if an alias is involved. + +## Aws Log Attributes + +This document defines attributes for AWS Logs. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------- | -------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `aws.log.group.arns` | string[] | The Amazon Resource Name(s) (ARN) of the AWS log group(s). [2] | `arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:*` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.log.group.names` | string[] | The name(s) of the AWS log group(s) an application is writing to. [3] | `/aws/lambda/my-function`; `opentelemetry-service` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.log.stream.arns` | string[] | The ARN(s) of the AWS log stream(s). [4] | `arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:log-stream:logs/main/10838bed-421f-43ef-870a-f43feacbbb5b` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.log.stream.names` | string[] | The name(s) of the AWS log stream(s) an application is writing to. | `logs/main/10838bed-421f-43ef-870a-f43feacbbb5b` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[2]:** See the [log group ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). + +**[3]:** Multiple log groups must be supported for cases like multi-container applications, where a single application has sidecar containers, and each write to their own log group. + +**[4]:** See the [log stream ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). One log group can contain several log streams, so these ARNs necessarily identify both a log group and a log stream. + +## Aws S3 Attributes + +This document defines attributes for AWS S3. + +| Attribute | Type | Description | Examples | Stability | +| -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `aws.s3.bucket` | string | The S3 bucket name the request refers to. Corresponds to the `--bucket` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [5] | `some-bucket-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.s3.copy_source` | string | The source object (in the form `bucket`/`key`) for the copy operation. [6] | `someFile.yml` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.s3.delete` | string | The delete request container that specifies the objects to be deleted. [7] | `Objects=[{Key=string,VersionId=string},{Key=string,VersionId=string}],Quiet=boolean` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.s3.key` | string | The S3 object key the request refers to. Corresponds to the `--key` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [8] | `someFile.yml` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.s3.part_number` | int | The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000. [9] | `3456` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.s3.upload_id` | string | Upload ID that identifies the multipart upload. [10] | `dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[5]:** The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter. +This applies to almost all S3 operations except `list-buckets`. + +**[6]:** The `copy_source` attribute applies to S3 copy operations and corresponds to the `--copy-source` parameter +of the [copy-object operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html). +This applies in particular to the following operations: + +- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) +- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) + +**[7]:** The `delete` attribute is only applicable to the [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) operation. +The `delete` attribute corresponds to the `--delete` parameter of the +[delete-objects operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-objects.html). + +**[8]:** The `key` attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter. +This applies in particular to the following operations: + +- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) +- [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) +- [get-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-object.html) +- [head-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/head-object.html) +- [put-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-object.html) +- [restore-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html) +- [select-object-content](https://docs.aws.amazon.com/cli/latest/reference/s3api/select-object-content.html) +- [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html) +- [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html) +- [create-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/create-multipart-upload.html) +- [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html) +- [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) +- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) + +**[9]:** The `part_number` attribute is only applicable to the [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) +and [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) operations. +The `part_number` attribute corresponds to the `--part-number` parameter of the +[upload-part operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html). + +**[10]:** The `upload_id` attribute applies to S3 multipart-upload operations and corresponds to the `--upload-id` parameter +of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) multipart operations. +This applies in particular to the following operations: + +- [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html) +- [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html) +- [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html) +- [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) +- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) diff --git a/docs/attributes-registry/browser.md b/docs/attributes-registry/browser.md new file mode 100644 index 0000000000..b41fd19074 --- /dev/null +++ b/docs/attributes-registry/browser.md @@ -0,0 +1,27 @@ + + + + + +# Browser + +## Browser Attributes + +The web browser attributes + +| Attribute | Type | Description | Examples | Stability | +| ------------------ | -------- | ----------------------------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------- | +| `browser.brands` | string[] | Array of brand name and version separated by a space [1] | ` Not A;Brand 99`; `Chromium 99`; `Chrome 99` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `browser.language` | string | Preferred language of the user using the browser [2] | `en`; `en-US`; `fr`; `fr-FR` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `browser.mobile` | boolean | A boolean that is true if the browser is running on a mobile device [3] | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `browser.platform` | string | The platform on which the browser is running [4] | `Windows`; `macOS`; `Android` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`). + +**[2]:** This value is intended to be taken from the Navigator API `navigator.language`. + +**[3]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.mobile`). If unavailable, this attribute SHOULD be left unset. + +**[4]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent. +The list of possible values is defined in the [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). Note that some (but not all) of these values can overlap with values in the [`os.type` and `os.name` attributes](./os.md). However, for consistency, the values in the `browser.platform` attribute should capture the exact value that the user agent provides. diff --git a/docs/attributes-registry/client.md b/docs/attributes-registry/client.md new file mode 100644 index 0000000000..5b72bfbba3 --- /dev/null +++ b/docs/attributes-registry/client.md @@ -0,0 +1,20 @@ + + + + + +# Client + +## Client Attributes + +These attributes may be used to describe the client in a connection-based network interaction where there is one side that initiates the connection (the client is the side that initiates the connection). This covers all TCP network interactions since TCP is connection-based and one side initiates the connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the protocol / API doesn't expose a clear notion of client and server). This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS. + +| Attribute | Type | Description | Examples | Stability | +| ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------- | +| `client.address` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `client.port` | int | Client port number. [2] | `65123` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. + +**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. diff --git a/docs/attributes-registry/cloud.md b/docs/attributes-registry/cloud.md new file mode 100644 index 0000000000..1eac23995a --- /dev/null +++ b/docs/attributes-registry/cloud.md @@ -0,0 +1,89 @@ + + + + + +# Cloud + +## Cloud Attributes + +A cloud environment (e.g. GCP, Azure, AWS). + +| Attribute | Type | Description | Examples | Stability | +| ------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `cloud.account.id` | string | The cloud account ID the resource is assigned to. | `111111111111`; `opentelemetry` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cloud.availability_zone` | string | Cloud regions often have multiple, isolated locations known as zones to increase availability. Availability zone represents the zone where the resource is running. [1] | `us-east-1c` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cloud.platform` | string | The cloud platform in use. [2] | `alibaba_cloud_ecs`; `alibaba_cloud_fc`; `alibaba_cloud_openshift` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cloud.provider` | string | Name of the cloud provider. | `alibaba_cloud`; `aws`; `azure` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cloud.region` | string | The geographical region the resource is running. [3] | `us-central1`; `us-east-1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cloud.resource_id` | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [4] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Availability zones are called "zones" on Alibaba Cloud and Google Cloud. + +**[2]:** The prefix of the service SHOULD match the one specified in `cloud.provider`. + +**[3]:** Refer to your provider's docs to see the available regions, for example [Alibaba Cloud regions](https://www.alibabacloud.com/help/doc-detail/40654.htm), [AWS regions](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/), [Azure regions](https://azure.microsoft.com/global-infrastructure/geographies/), [Google Cloud regions](https://cloud.google.com/about/locations), or [Tencent Cloud regions](https://www.tencentcloud.com/document/product/213/6091). + +**[4]:** On some cloud providers, it may not be possible to determine the full ID at startup, +so it may be necessary to set `cloud.resource_id` as a span attribute instead. + +The exact value to use for `cloud.resource_id` depends on the cloud provider. +The following well-known definitions MUST be used if you set this attribute and they apply: + +- **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). + Take care not to use the "invoked ARN" directly but replace any + [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) + with the resolved function version, as the same runtime instance may be invokable with + multiple different aliases. +- **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) +- **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/rest/api/resources/resources/get-by-id) of the invoked function, + _not_ the function app, having the form + `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/`. + This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share + a TracerProvider. + +`cloud.platform` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --------------------------- | ---------------------------------------------- | ---------------------------------------------------------------- | +| `alibaba_cloud_ecs` | Alibaba Cloud Elastic Compute Service | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `alibaba_cloud_fc` | Alibaba Cloud Function Compute | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `alibaba_cloud_openshift` | Red Hat OpenShift on Alibaba Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws_ec2` | AWS Elastic Compute Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws_ecs` | AWS Elastic Container Service | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws_eks` | AWS Elastic Kubernetes Service | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws_lambda` | AWS Lambda | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws_elastic_beanstalk` | AWS Elastic Beanstalk | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws_app_runner` | AWS App Runner | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws_openshift` | Red Hat OpenShift on AWS (ROSA) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure_vm` | Azure Virtual Machines | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure_container_apps` | Azure Container Apps | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure_container_instances` | Azure Container Instances | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure_aks` | Azure Kubernetes Service | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure_functions` | Azure Functions | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure_app_service` | Azure App Service | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure_openshift` | Azure Red Hat OpenShift | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp_bare_metal_solution` | Google Bare Metal Solution (BMS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp_compute_engine` | Google Cloud Compute Engine (GCE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp_cloud_run` | Google Cloud Run | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp_kubernetes_engine` | Google Cloud Kubernetes Engine (GKE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp_cloud_functions` | Google Cloud Functions (GCF) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp_app_engine` | Google Cloud App Engine (GAE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp_openshift` | Red Hat OpenShift on Google Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ibm_cloud_openshift` | Red Hat OpenShift on IBM Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tencent_cloud_cvm` | Tencent Cloud Cloud Virtual Machine (CVM) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tencent_cloud_eks` | Tencent Cloud Elastic Kubernetes Service (EKS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tencent_cloud_scf` | Tencent Cloud Serverless Cloud Function (SCF) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`cloud.provider` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --------------- | ---------------------------- | ---------------------------------------------------------------- | +| `alibaba_cloud` | Alibaba Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws` | Amazon Web Services | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure` | Microsoft Azure | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp` | Google Cloud Platform | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `heroku` | Heroku Platform as a Service | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ibm_cloud` | IBM Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tencent_cloud` | Tencent Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/cloudevents.md b/docs/attributes-registry/cloudevents.md new file mode 100644 index 0000000000..86868e920f --- /dev/null +++ b/docs/attributes-registry/cloudevents.md @@ -0,0 +1,19 @@ + + + + + +# CloudEvents + +## Cloudevents Attributes + +This document defines attributes for CloudEvents. + +| Attribute | Type | Description | Examples | Stability | +| -------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event. | `123e4567-e89b-12d3-a456-426614174000`; `0001` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cloudevents.event_source` | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cloudevents.event_spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses. | `1.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/code.md b/docs/attributes-registry/code.md new file mode 100644 index 0000000000..752171c68b --- /dev/null +++ b/docs/attributes-registry/code.md @@ -0,0 +1,20 @@ + + + + + +# Code + +## Code Attributes + +These attributes allow to report this unit of code and therefore to provide more context about the span. + +| Attribute | Type | Description | Examples | Stability | +| ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | +| `code.column` | int | The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `16` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `code.filepath` | string | The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). | `/usr/local/MyApplication/content_root/app/index.php` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `code.function` | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `code.lineno` | int | The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `42` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `code.namespace` | string | The "namespace" within which `code.function` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. | `com.example.MyHttpService` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `code.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/container.md b/docs/attributes-registry/container.md new file mode 100644 index 0000000000..eb62fd417f --- /dev/null +++ b/docs/attributes-registry/container.md @@ -0,0 +1,53 @@ + + + + + +# Container + +- [Container](#container-attributes) +- [Container Deprecated](#container-deprecated-attributes) + +## Container Attributes + +A container instance. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `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`; `system`; `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) | +| `container.image.repo_digests` | string[] | Repo digests of the container image as provided by the container runtime. [3] | `example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb`; `internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `container.image.tags` | string[] | Container image tags. An example can be found in [Docker Image Inspect](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect). Should be only the `` section of the full name for example from `registry.example.com/my-org/my-image:`. | `v1.27.1`; `3.5.7-0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `container.label.` | string | Container labels, `` being the label name, the value being the label value. | `container.label.app=nginx` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `container.name` | string | Container name used by container runtime. | `opentelemetry-autoconf` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `container.runtime` | string | The container runtime managing this container. | `docker`; `containerd`; `rkt` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. + +**[2]:** Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) endpoint. +K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`. +The ID is assigned by the container runtime and can vary in different environments. Consider using `oci.manifest.digest` if it is important to identify the same image in different environments/runtimes. + +**[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 | +| -------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `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) | +| `system` | When CPU is used by the system (host OS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `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) | + +## Container Deprecated Attributes + +Describes deprecated container attributes. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------ | ------ | ------------------------------------------ | --------------------------- | --------------------------------------------------------------------------------------------- | +| `container.labels.` | string | Deprecated, use `container.label` instead. | `container.label.app=nginx` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `container.label`. | diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md new file mode 100644 index 0000000000..2f0f35303e --- /dev/null +++ b/docs/attributes-registry/db.md @@ -0,0 +1,219 @@ + + + + + +# Db + +- [Db](#db-attributes) +- [Db Cassandra](#db-cassandra-attributes) +- [Db Cosmosdb](#db-cosmosdb-attributes) +- [Db Deprecated](#db-deprecated-attributes) +- [Db Elasticsearch](#db-elasticsearch-attributes) +- [Db Metrics Deprecated](#db-metrics-deprecated-attributes) + +## Db Attributes + +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`; `used` | ![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.name` | string | The name of the operation or command being executed. | `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. [3] | `someval`; `55` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.query.text` | string | The database query being executed. | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql`; `mssql`; `mssqlcompact` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. + +**[2]:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid. +Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. + +**[3]:** 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. + +`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` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `used` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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 | +| --------------- | -------------------------------------------------- | ---------------------------------------------------------------- | +| `other_sql` | Some other SQL database. Fallback only. See notes. | ![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) | +| `oracle` | Oracle Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db2` | IBM Db2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `postgresql` | PostgreSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `redshift` | Amazon Redshift | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hive` | Apache Hive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cloudscape` | Cloudscape | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hsqldb` | HyperSQL DataBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `progress` | Progress Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `maxdb` | SAP MaxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hanadb` | SAP HANA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ingres` | Ingres | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `firstsql` | FirstSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `edb` | EnterpriseDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `adabas` | Adabas (Adaptable Database System) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `firebird` | Firebird | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `derby` | Apache Derby | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `filemaker` | FileMaker | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `informix` | Informix | ![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) | +| `netezza` | Netezza | ![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) | +| `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) | +| `vertica` | Vertica | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `h2` | H2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `coldfusion` | ColdFusion IMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cassandra` | Apache Cassandra | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hbase` | Apache HBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `redis` | Redis | ![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) | +| `cosmosdb` | Microsoft Azure Cosmos DB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dynamodb` | Amazon DynamoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `geode` | Apache Geode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `elasticsearch` | Elasticsearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cockroachdb` | CockroachDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `opensearch` | OpenSearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `clickhouse` | ClickHouse | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `spanner` | Cloud Spanner | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `trino` | Trino | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Db Cassandra Attributes + +This group defines attributes for Cassandra. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------- | +| `db.cassandra.consistency_level` | string | The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). | `all`; `each_quorum`; `quorum` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cassandra.coordinator.dc` | string | The data center of the coordinating node for a query. | `us-west-2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cassandra.coordinator.id` | string | The ID of the coordinating node for a query. | `be13faa2-8574-4d71-926d-27f16cf8a7af` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cassandra.idempotence` | boolean | Whether or not the query is idempotent. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cassandra.page_size` | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cassandra.speculative_execution_count` | int | The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. | `0`; `2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`db.cassandra.consistency_level` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------------- | ----------- | ---------------------------------------------------------------- | +| `all` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `each_quorum` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `quorum` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `local_quorum` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `one` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `two` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `three` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `local_one` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `any` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `serial` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `local_serial` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Db Cosmosdb Attributes + +This group defines attributes for Azure Cosmos DB. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------------------ | ------ | --------------------------------- | -------------------------------------- | ---------------------------------------------------------------- | +| `db.cosmosdb.client_id` | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.connection_mode` | string | Cosmos client connection mode. | `gateway`; `direct` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.operation_type` | string | CosmosDB Operation Type. | `Invalid`; `Create`; `Patch` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.request_charge` | double | RU consumed for that operation | `46.18`; `1.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.request_content_length` | int | Request payload size in bytes | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.status_code` | int | Cosmos DB status code. | `200`; `201` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.sub_status_code` | int | Cosmos DB sub status code. | `1000`; `1002` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`db.cosmosdb.connection_mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --------- | ------------------------------- | ---------------------------------------------------------------- | +| `gateway` | Gateway (HTTP) connections mode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `direct` | Direct connection. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`db.cosmosdb.operation_type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------------------- | ----------- | ---------------------------------------------------------------- | +| `Invalid` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Create` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Patch` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Read` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ReadFeed` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Delete` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Replace` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Execute` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Query` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Head` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `HeadFeed` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Upsert` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Batch` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `QueryPlan` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ExecuteJavaScript` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Db Deprecated Attributes + +"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. | + +## Db Elasticsearch Attributes + +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. [4] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[4]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names. + +## Db Metrics Deprecated Attributes + +"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`; `used` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.client.connections.state`. | + +`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` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `used` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/deployment.md b/docs/attributes-registry/deployment.md new file mode 100644 index 0000000000..97c68f3ebf --- /dev/null +++ b/docs/attributes-registry/deployment.md @@ -0,0 +1,23 @@ + + + + + +# Deployment + +## Deployment Attributes + +This document defines attributes for software deployments. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------ | ----------------------- | ---------------------------------------------------------------- | +| `deployment.environment` | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** `deployment.environment` does not affect the uniqueness constraints defined through +the `service.namespace`, `service.name` and `service.instance.id` resource attributes. +This implies that resources carrying the following attribute combinations MUST be +considered to be identifying the same service: + +- `service.name=frontend`, `deployment.environment=production` +- `service.name=frontend`, `deployment.environment=staging`. diff --git a/docs/attributes-registry/destination.md b/docs/attributes-registry/destination.md new file mode 100644 index 0000000000..23b35bbcd1 --- /dev/null +++ b/docs/attributes-registry/destination.md @@ -0,0 +1,18 @@ + + + + + +# Destination + +## Destination Attributes + +These attributes may be used to describe the receiver of a network exchange/packet. These should be used when there is no client/server relationship between the two sides, or when that relationship is unknown. This covers low-level network interactions (e.g. packet tracing) where you don't know if there was a connection or which side initiated it. This also covers unidirectional UDP flows and peer-to-peer communication where the "user-facing" surface of the protocol / API doesn't expose a clear notion of client and server. + +| Attribute | Type | Description | Examples | Stability | +| --------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------- | +| `destination.address` | string | Destination address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `destination.example.com`; `10.1.2.80`; `/tmp/my.sock` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `destination.port` | int | Destination port number | `3389`; `2888` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent the destination address behind any intermediaries, for example proxies, if it's available. diff --git a/docs/attributes-registry/device.md b/docs/attributes-registry/device.md new file mode 100644 index 0000000000..3ce6b15385 --- /dev/null +++ b/docs/attributes-registry/device.md @@ -0,0 +1,26 @@ + + + + + +# Device + +## Device Attributes + +Describes device attributes. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------- | ------ | ----------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------- | +| `device.id` | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `device.manufacturer` | string | The name of the device manufacturer [2] | `Apple`; `Samsung` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `device.model.identifier` | string | The model identifier for the device [3] | `iPhone3,4`; `SM-G920F` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `device.model.name` | string | The marketing name for the device model [4] | `iPhone 6s Plus`; `Samsung Galaxy S6` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The device identifier MUST only be defined using the values outlined below. This value is not an advertising identifier and MUST NOT be used as such. On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) on best practices and exact implementation details. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence. + +**[2]:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`. + +**[3]:** It's recommended this value represents a machine-readable version of the model identifier rather than the market or consumer-friendly name of the device. + +**[4]:** It's recommended this value represents a human-readable version of the device model rather than a machine-readable alternative. diff --git a/docs/attributes-registry/disk.md b/docs/attributes-registry/disk.md new file mode 100644 index 0000000000..1dfa838a62 --- /dev/null +++ b/docs/attributes-registry/disk.md @@ -0,0 +1,22 @@ + + + + + +# Disk + +## Disk Attributes + +These attributes may be used for any disk related operation. + +| Attribute | Type | Description | Examples | Stability | +| ------------------- | ------ | -------------------------------- | --------------- | ---------------------------------------------------------------- | +| `disk.io.direction` | string | The disk IO operation direction. | `read`; `write` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`disk.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------- | ----------- | ---------------------------------------------------------------- | +| `read` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `write` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/dns.md b/docs/attributes-registry/dns.md new file mode 100644 index 0000000000..6345d59240 --- /dev/null +++ b/docs/attributes-registry/dns.md @@ -0,0 +1,17 @@ + + + + + +# Dns + +## Dns Attributes + +This document defines the shared attributes used to report a DNS query. + +| Attribute | Type | Description | Examples | Stability | +| ------------------- | ------ | --------------------------- | ------------------------------------- | ---------------------------------------------------------------- | +| `dns.question.name` | string | The name being queried. [1] | `www.example.com`; `opentelemetry.io` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** If the name field contains non-printable characters (below 32 or above 126), those characters should be represented as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. Tabs, carriage returns, and line feeds should be converted to \t, \r, and \n respectively. diff --git a/docs/attributes-registry/enduser.md b/docs/attributes-registry/enduser.md new file mode 100644 index 0000000000..9fa388eeac --- /dev/null +++ b/docs/attributes-registry/enduser.md @@ -0,0 +1,17 @@ + + + + + +# Enduser + +## Enduser Attributes + +This document defines attributes for operations with an authenticated and/or authorized enduser. + +| Attribute | Type | Description | Examples | Stability | +| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------- | +| `enduser.id` | string | Username or client_id extracted from the access token or [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) header in the inbound request from outside the system. | `username` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `enduser.role` | string | Actual/assumed role the client is making the request under extracted from token or application security context. | `admin` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `enduser.scope` | string | Scopes or granted authorities the client currently possesses extracted from token or application security context. The value would come from the scope associated with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3) or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). | `read:message, write:files` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/error.md b/docs/attributes-registry/error.md new file mode 100644 index 0000000000..d74465057f --- /dev/null +++ b/docs/attributes-registry/error.md @@ -0,0 +1,41 @@ + + + + + +# Error + +## Error Attributes + +This document defines the shared attributes used to report an error. + +| Attribute | Type | Description | Examples | Stability | +| ------------ | ------ | -------------------------------------------------------- | -------- | ---------------------------------------------------------- | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `_OTHER` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[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. + +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low. +Telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time when no +additional filters are applied. + +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), +it's RECOMMENDED to: + +- Use a domain-specific attribute +- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. + +`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------- | +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/attributes-registry/event.md b/docs/attributes-registry/event.md new file mode 100644 index 0000000000..049ae6066f --- /dev/null +++ b/docs/attributes-registry/event.md @@ -0,0 +1,17 @@ + + + + + +# Event + +## Event Attributes + +Attributes for Events represented using Log Records. + +| Attribute | Type | Description | Examples | Stability | +| ------------ | ------ | ----------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------- | +| `event.name` | string | Identifies the class / type of event. [1] | `browser.mouse.click`; `device.app.lifecycle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Event names are subject to the same rules as [attribute names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/common/attribute-naming.md). Notably, event names are namespaced to avoid collisions and provide a clean separation of semantics for events in separate domains like browser, mobile, and kubernetes. diff --git a/docs/attributes-registry/exception.md b/docs/attributes-registry/exception.md new file mode 100644 index 0000000000..7bc639e34a --- /dev/null +++ b/docs/attributes-registry/exception.md @@ -0,0 +1,35 @@ + + + + + +# Exception + +## Exception Attributes + +This document defines the shared attributes used to report a single exception associated with a span or log. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- | +| `exception.escaped` | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] | | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** An exception is considered to have escaped (or left) the scope of a span, +if that span is ended while the exception is still logically "in flight". +This may be actually "in flight" in some languages (e.g. if the exception +is passed to a Context manager's `__exit__` method in Python) but will +usually be caught at the point of recording the exception in most languages. + +It is usually not possible to determine at the point where an exception is thrown +whether it will escape the scope of a span. +However, it is trivial to know that an exception +will escape, if one checks for an active exception just before ending the span, +as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). + +It follows that an exception may still escape the scope of the span +even if the `exception.escaped` attribute was not set or set to false, +since the event might have been recorded at a time where it was not +clear whether the exception will escape. diff --git a/docs/attributes-registry/faas.md b/docs/attributes-registry/faas.md new file mode 100644 index 0000000000..fd7a4bcd0d --- /dev/null +++ b/docs/attributes-registry/faas.md @@ -0,0 +1,95 @@ + + + + + +# Faas + +## Faas Attributes + +FaaS attributes + +| Attribute | Type | Description | Examples | Stability | +| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------- | +| `faas.coldstart` | boolean | A boolean that is true if the serverless function is executed for the first time (aka cold-start). | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `faas.cron` | string | A string containing the schedule period as [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). | `0/5 * * * ? *` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `faas.document.collection` | string | The name of the source on which the triggering operation was performed. For example, in Cloud Storage or S3 corresponds to the bucket name, and in Cosmos DB to the database name. | `myBucketName`; `myDbName` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `faas.document.name` | string | The document name/table subjected to the operation. For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table name. | `myFile.txt`; `myTableName` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `faas.document.operation` | string | Describes the type of the operation that was performed on the data. | `insert`; `edit`; `delete` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `faas.document.time` | string | A string containing the time when the data was accessed in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `faas.instance` | string | The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version. [1] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `faas.invocation_id` | string | The invocation ID of the current function invocation. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `faas.invoked_name` | string | The name of the invoked function. [2] | `my-function` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `faas.invoked_provider` | string | The cloud provider of the invoked function. [3] | `alibaba_cloud`; `aws`; `azure` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `faas.invoked_region` | string | The cloud region of the invoked function. [4] | `eu-central-1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `faas.max_memory` | int | The amount of memory available to the serverless function converted to Bytes. [5] | `134217728` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `faas.name` | string | The name of the single function that this runtime instance executes. [6] | `my-function`; `myazurefunctionapp/some-function-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `faas.time` | string | A string containing the function invocation time in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `faas.version` | string | The immutable version of the function being executed. [7] | `26`; `pinkfroid-00002` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** \* **AWS Lambda:** Use the (full) log stream name. + +**[2]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function. + +**[3]:** SHOULD be equal to the `cloud.provider` resource attribute of the invoked function. + +**[4]:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function. + +**[5]:** It's recommended to set this attribute since e.g. too little memory can easily stop a Java AWS Lambda function from working correctly. On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` provides this information (which must be multiplied by 1,048,576). + +**[6]:** This is the name of the function as configured/deployed on the FaaS +platform and is usually different from the name of the callback +function (which may be stored in the +[`code.namespace`/`code.function`](/docs/general/attributes.md#source-code-attributes) +span attributes). + +For some cloud providers, the above definition is ambiguous. The following +definition of function name MUST be used for this attribute +(and consequently the span name) for the listed cloud providers/products: + +- **Azure:** The full name `/`, i.e., function app name + followed by a forward slash followed by the function name (this form + can also be seen in the resource JSON for the function). + This means that a span attribute MUST be used, as an Azure function + app can host multiple functions that would usually share + a TracerProvider (see also the `cloud.resource_id` attribute). + +**[7]:** Depending on the cloud provider and platform, use: + +- **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) + (an integer represented as a decimal string). +- **Google Cloud Run (Services):** The [revision](https://cloud.google.com/run/docs/managing/revisions) + (i.e., the function name plus the revision suffix). +- **Google Cloud Functions:** The value of the + [`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically). +- **Azure Functions:** Not applicable. Do not set this attribute. + +`faas.document.operation` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------- | ----------------------------- | ---------------------------------------------------------------- | +| `insert` | When a new object is created. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `edit` | When an object is modified. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `delete` | When an object is deleted. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`faas.invoked_provider` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --------------- | --------------------- | ---------------------------------------------------------------- | +| `alibaba_cloud` | Alibaba Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws` | Amazon Web Services | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure` | Microsoft Azure | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp` | Google Cloud Platform | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tencent_cloud` | Tencent Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------------ | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | +| `datasource` | A response to some data source operation such as a database or filesystem read/write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http` | To provide an answer to an inbound HTTP request | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `timer` | A function is scheduled to be executed regularly | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other` | If none of the others apply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md new file mode 100644 index 0000000000..e752cc6172 --- /dev/null +++ b/docs/attributes-registry/feature-flag.md @@ -0,0 +1,26 @@ + + + + + +# Feature Flag + +## Feature Flag Attributes + +This document defines attributes for Feature Flags. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- | ------------------- | ---------------------------------------------------------------- | +| `feature_flag.key` | string | The unique identifier of the feature flag. | `logo-color` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.provider_name` | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.variant` | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** A semantic identifier, commonly referred to as a variant, provides a means +for referring to a value without including the value itself. This can +provide additional context for understanding the meaning behind a value. +For example, the variant `red` maybe be used for the value `#c05543`. + +A stringified version of the value can be used in situations where a +semantic identifier is unavailable. String representation of the value +should be determined by the implementer. diff --git a/docs/attributes-registry/file.md b/docs/attributes-registry/file.md new file mode 100644 index 0000000000..eb9a4140dc --- /dev/null +++ b/docs/attributes-registry/file.md @@ -0,0 +1,21 @@ + + + + + +# File + +## File Attributes + +Describes file attributes. + +| Attribute | Type | Description | Examples | Stability | +| ---------------- | ------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------- | +| `file.directory` | string | Directory where the file is located. It should include the drive letter, when appropriate. | `/home/user`; `C:\Program Files\MyApp` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.extension` | string | File extension, excluding the leading dot. [1] | `png`; `gz` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.name` | string | Name of the file including the extension, without the directory. | `example.png` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.path` | string | Full path to the file, including the file name. It should include the drive letter, when appropriate. | `/home/alice/example.png`; `C:\Program Files\MyApp\myapp.exe` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.size` | int | File size in bytes. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** When the file name has multiple extensions (example.tar.gz), only the last one should be captured ("gz", not "tar.gz"). diff --git a/docs/attributes-registry/gcp.md b/docs/attributes-registry/gcp.md new file mode 100644 index 0000000000..66bb310a3d --- /dev/null +++ b/docs/attributes-registry/gcp.md @@ -0,0 +1,28 @@ + + + + + +# GCP + +- [Gcp Cloud Run](#gcp-cloud-run-attributes) +- [Gcp Gce](#gcp-gce-attributes) + +## Gcp Cloud Run Attributes + +This document defines attributes for Google Cloud Run. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------- | +| `gcp.cloud_run.job.execution` | string | The name of the Cloud Run [execution](https://cloud.google.com/run/docs/managing/job-executions) being run for the Job, as set by the [`CLOUD_RUN_EXECUTION`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `job-name-xxxx`; `sample-job-mdw84` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp.cloud_run.job.task_index` | int | The index for a task within an execution as provided by the [`CLOUD_RUN_TASK_INDEX`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `0`; `1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Gcp Gce Attributes + +This document defines attributes for Google Compute Engine (GCE). + +| Attribute | Type | Description | Examples | Stability | +| --------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `gcp.gce.instance.hostname` | string | The hostname of a GCE instance. This is the full value of the default or [custom hostname](https://cloud.google.com/compute/docs/instances/custom-hostname-vm). | `my-host1234.example.com`; `sample-vm.us-west1-b.c.my-project.internal` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp.gce.instance.name` | string | The instance name of a GCE instance. This is the value provided by `host.name`, the visible name of the instance in the Cloud Console UI, and the prefix for the default hostname of the instance as defined by the [default internal DNS name](https://cloud.google.com/compute/docs/internal-dns#instance-fully-qualified-domain-names). | `instance-1`; `my-vm-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/gen-ai.md b/docs/attributes-registry/gen-ai.md new file mode 100644 index 0000000000..e5853b5363 --- /dev/null +++ b/docs/attributes-registry/gen-ai.md @@ -0,0 +1,35 @@ + + + + + +# Gen AI + +## 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.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 name of the LLM foundation model vendor. | `openai` | ![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) | + +**[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) + +`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 | +| -------- | ----------- | ---------------------------------------------------------------- | +| `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/graphql.md b/docs/attributes-registry/graphql.md new file mode 100644 index 0000000000..5561a1b31a --- /dev/null +++ b/docs/attributes-registry/graphql.md @@ -0,0 +1,27 @@ + + + + + +# GraphQL + +## Graphql Attributes + +This document defines attributes for GraphQL. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------ | ------ | ----------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------- | +| `graphql.document` | string | The GraphQL document being executed. [1] | `query findBookById { bookById(id: ?) { name } }` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `graphql.operation.name` | string | The name of the operation being executed. | `findBookById` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `graphql.operation.type` | string | The type of the operation being executed. | `query`; `mutation`; `subscription` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The value may be sanitized to exclude sensitive information. + +`graphql.operation.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------------- | -------------------- | ---------------------------------------------------------------- | +| `query` | GraphQL query | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mutation` | GraphQL mutation | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `subscription` | GraphQL subscription | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/heroku.md b/docs/attributes-registry/heroku.md new file mode 100644 index 0000000000..e8773409c3 --- /dev/null +++ b/docs/attributes-registry/heroku.md @@ -0,0 +1,17 @@ + + + + + +# Heroku + +## Heroku Attributes + +This document defines attributes for the Android platform on which the Android application is running. + +| Attribute | Type | Description | Examples | Stability | +| ----------------------------------- | ------ | ------------------------------------- | --------------------------------------- | ---------------------------------------------------------------- | +| `heroku.app.id` | string | Unique identifier for the application | `2daa2797-e42b-4624-9322-ec3f968df4da` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `heroku.release.commit` | string | Commit hash for the current release | `e6134959463efd8966b20e75b913cafe3f5ec` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `heroku.release.creation_timestamp` | string | Time and date the release was created | `2022-10-23T18:00:42Z` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/host.md b/docs/attributes-registry/host.md new file mode 100644 index 0000000000..3f51db07dc --- /dev/null +++ b/docs/attributes-registry/host.md @@ -0,0 +1,48 @@ + + + + + +# Host + +## Host Attributes + +A host is defined as a computing instance. For example, physical servers, virtual machines, switches or disk array. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------- | +| `host.arch` | string | The CPU architecture the host system is running on. | `amd64`; `arm32`; `arm64` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `host.cpu.cache.l2.size` | int | The amount of level 2 memory cache available to the processor (in Bytes). | `12288000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `host.cpu.family` | string | Family or generation of the CPU. | `6`; `PA-RISC 1.1e` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `host.cpu.model.id` | string | Model identifier. It provides more granular information about the CPU, distinguishing it from other CPUs within the same family. | `6`; `9000/778/B180L` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `host.cpu.model.name` | string | Model designation of the processor. | `11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `host.cpu.stepping` | string | Stepping or core revisions. | `1`; `r1p1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `host.cpu.vendor.id` | string | Processor manufacturer identifier. A maximum 12-character string. [1] | `GenuineIntel` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `host.id` | string | Unique host ID. For Cloud, this must be the instance_id assigned by the cloud provider. For non-containerized systems, this should be the `machine-id`. See the table below for the sources to use to determine the `machine-id` based on operating system. | `fdbf79e8af94cb7f9e8df36789187052` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `host.image.id` | string | VM image ID or host OS image ID. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `host.image.name` | string | Name of the VM image or OS install the host was instantiated from. | `infra-ami-eks-worker-node-7d4ec78312`; `CentOS-8-x86_64-1905` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `host.image.version` | string | The version string of the VM image or host OS as defined in [Version Attributes](/docs/resource/README.md#version-attributes). | `0.1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `host.ip` | string[] | Available IP addresses of the host, excluding loopback interfaces. [2] | `192.168.1.140`; `fe80::abc2:4a28:737a:609e` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `host.mac` | string[] | Available MAC addresses of the host, excluding loopback interfaces. [3] | `AC-DE-48-23-45-67`; `AC-DE-48-23-45-67-01-9F` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `host.name` | string | Name of the host. On Unix systems, it may contain what the hostname command returns, or the fully qualified hostname, or another name specified by the user. | `opentelemetry-test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `host.type` | string | Type of host. For Cloud, this must be the machine type. | `n1-standard-1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** [CPUID](https://wiki.osdev.org/CPUID) command returns the vendor ID string in EBX, EDX and ECX registers. Writing these to memory in this order results in a 12-character string. + +**[2]:** IPv4 Addresses MUST be specified in dotted-quad notation. IPv6 addresses MUST be specified in the [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952.html) format. + +**[3]:** MAC Addresses MUST be represented in [IEEE RA hexadecimal form](https://standards.ieee.org/wp-content/uploads/import/documents/tutorials/eui.pdf): as hyphen-separated octets in uppercase hexadecimal form from most to least significant. + +`host.arch` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------- | ------------------ | ---------------------------------------------------------------- | +| `amd64` | AMD64 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `arm32` | ARM32 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `arm64` | ARM64 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ia64` | Itanium | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ppc32` | 32-bit PowerPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ppc64` | 64-bit PowerPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `s390x` | IBM z/Architecture | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `x86` | 32-bit x86 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/http.md b/docs/attributes-registry/http.md new file mode 100644 index 0000000000..5877bc0421 --- /dev/null +++ b/docs/attributes-registry/http.md @@ -0,0 +1,106 @@ + + + + + +# HTTP + +- [Http](#http-attributes) +- [Http Deprecated](#http-deprecated-attributes) + +## Http Attributes + +This document defines semantic convention attributes in the HTTP namespace. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `http.connection.state` | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http.request.body.size` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http.request.header.` | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [1] | `http.request.header.content-type=["application/json"]`; `http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `http.request.method` | string | HTTP request method. [2] | `CONNECT`; `DELETE`; `GET` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `http.request.method_original` | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `http.request.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [3] | `3` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `http.request.size` | int | The total size of the request in bytes. This should be the total number of bytes sent over the wire, including the request line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and request body if any. | `1437` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http.response.body.size` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http.response.header.` | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [4] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `http.response.size` | int | The total size of the response in bytes. This should be the total number of bytes sent over the wire, including the status line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and response body and trailers if any. | `1437` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `http.route` | string | The matched route, that is, the path template in the format used by the respective server framework. [5] | `/users/:userID?`; `{controller}/{action}/{id?}` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +The `User-Agent` header is already captured in the `user_agent.original` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. +The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. + +**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. +By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). + +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. + +If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override +the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named +OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods +(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). + +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. +Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. +Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. + +**[3]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other). + +**[4]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +Users MAY explicitly configure instrumentations to capture them even though it is not recommended. +The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. + +**[5]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. + +`http.connection.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------- | ------------- | ---------------------------------------------------------------- | +| `active` | active state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `idle` | idle state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --------- | ------------------------------------------------------------------- | ---------------------------------------------------------- | +| `CONNECT` | CONNECT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `DELETE` | DELETE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `GET` | GET method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `HEAD` | HEAD method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `OPTIONS` | OPTIONS method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PATCH` | PATCH method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `POST` | POST method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +## Http Deprecated Attributes + +Describes deprecated HTTP attributes. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------------ | ------ | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| `http.flavor` | string | Deprecated, use `network.protocol.name` instead. | `1.0`; `1.1`; `2.0` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `network.protocol.name`. | +| `http.method` | string | Deprecated, use `http.request.method` instead. | `GET`; `POST`; `HEAD` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.request.method`. | +| `http.request_content_length` | int | Deprecated, use `http.request.header.content-length` instead. | `3495` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.request.header.content-length`. | +| `http.response_content_length` | int | Deprecated, use `http.response.header.content-length` instead. | `3495` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.response.header.content-length`. | +| `http.scheme` | string | Deprecated, use `url.scheme` instead. | `http`; `https` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `url.scheme` instead. | +| `http.status_code` | int | Deprecated, use `http.response.status_code` instead. | `200` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.response.status_code`. | +| `http.target` | string | Deprecated, use `url.path` and `url.query` instead. | `/search?q=OpenTelemetry#SemConv` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Split to `url.path` and `url.query. | +| `http.url` | string | Deprecated, use `url.full` instead. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `url.full`. | +| `http.user_agent` | string | Deprecated, use `user_agent.original` instead. | `CERN-LineMode/2.15 libwww/2.17b3`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `user_agent.original`. | + +`http.flavor` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------ | -------------- | ---------------------------------------------------------------- | +| `1.0` | HTTP/1.0 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `1.1` | HTTP/1.1 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `2.0` | HTTP/2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `3.0` | HTTP/3 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `SPDY` | SPDY protocol. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `QUIC` | QUIC protocol. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/ios.md b/docs/attributes-registry/ios.md new file mode 100644 index 0000000000..11e2b8e1a9 --- /dev/null +++ b/docs/attributes-registry/ios.md @@ -0,0 +1,27 @@ + + + + + +# iOS + +## Ios Deprecated Attributes + +The iOS platform on which the iOS application is running. + +| Attribute | Type | Description | Examples | Stability | +| ----------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| `ios.state` | string | Deprecated use the `device.app.lifecycle` event definition including `ios.state` as a payload field instead. [1] | `active`; `inactive`; `background` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Moved to a payload field of `device.app.lifecycle`. | + +**[1]:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived. + +`ios.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------------ | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `active` | The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `inactive` | The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `background` | The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `foreground` | The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `terminate` | The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/jvm.md b/docs/attributes-registry/jvm.md new file mode 100644 index 0000000000..9e438896bb --- /dev/null +++ b/docs/attributes-registry/jvm.md @@ -0,0 +1,44 @@ + + + + + +# JVM + +## Jvm Attributes + +This document defines Java Virtual machine related attributes. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------- | ------- | ----------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------- | +| `jvm.gc.action` | string | Name of the garbage collector action. [1] | `end of minor GC`; `end of major GC` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `jvm.gc.name` | string | Name of the garbage collector. [2] | `G1 Young Generation`; `G1 Old Generation` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `jvm.memory.pool.name` | string | Name of the memory pool. [3] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `jvm.thread.daemon` | boolean | Whether the thread is daemon or not. | | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `jvm.thread.state` | string | State of the thread. | `new`; `runnable`; `blocked` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](). + +**[2]:** Garbage collector name is generally obtained via [GarbageCollectionNotificationInfo#getGcName()](). + +**[3]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](). + +`jvm.memory.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ---------- | --------------- | ---------------------------------------------------------- | +| `heap` | Heap memory. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `non_heap` | Non-heap memory | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`jvm.thread.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | +| `new` | A thread that has not yet started is in this state. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `runnable` | A thread executing in the Java virtual machine is in this state. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `blocked` | A thread that is blocked waiting for a monitor lock is in this state. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `waiting` | A thread that is waiting indefinitely for another thread to perform a particular action is in this state. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `timed_waiting` | A thread that is waiting for another thread to perform an action for up to a specified waiting time is in this state. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `terminated` | A thread that has exited is in this state. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/attributes-registry/k8s.md b/docs/attributes-registry/k8s.md new file mode 100644 index 0000000000..b9bc225333 --- /dev/null +++ b/docs/attributes-registry/k8s.md @@ -0,0 +1,72 @@ + + + + + +# K8s + +- [K8s](#k8s-attributes) +- [K8s Deprecated](#k8s-deprecated-attributes) + +## K8s Attributes + +Kubernetes resource attributes. + +| Attribute | Type | Description | Examples | Stability | +| --------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `k8s.cluster.name` | string | The name of the cluster. | `opentelemetry-cluster` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.cluster.uid` | string | A pseudo-ID for the cluster, set to the UID of the `kube-system` namespace. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.container.name` | string | The name of the Container from Pod specification, must be unique within a Pod. Container runtime usually uses different globally unique name (`container.name`). | `redis` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.container.restart_count` | int | Number of times the container was restarted. This attribute can be used to identify a particular container (running or stopped) within a container spec. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.container.status.last_terminated_reason` | string | Last terminated reason of the Container. | `Evicted`; `Error` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.cronjob.name` | string | The name of the CronJob. | `opentelemetry` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.cronjob.uid` | string | The UID of the CronJob. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.daemonset.name` | string | The name of the DaemonSet. | `opentelemetry` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.daemonset.uid` | string | The UID of the DaemonSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.deployment.name` | string | The name of the Deployment. | `opentelemetry` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.deployment.uid` | string | The UID of the Deployment. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.job.name` | string | The name of the Job. | `opentelemetry` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.job.uid` | string | The UID of the Job. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.namespace.name` | string | The name of the namespace that the pod is running in. | `default` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.node.name` | string | The name of the Node. | `node-1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.node.uid` | string | The UID of the Node. | `1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.pod.annotation.` | string | The annotation key-value pairs placed on the Pod, the `` being the annotation name, the value being the annotation value. | `k8s.pod.annotation.kubernetes.io/enforce-mountable-secrets=true`; `k8s.pod.annotation.mycompany.io/arch=x64`; `k8s.pod.annotation.data=` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.pod.label.` | string | The label key-value pairs placed on the Pod, the `` being the label name, the value being the label value. | `k8s.pod.label.app=my-app`; `k8s.pod.label.mycompany.io/arch=x64`; `k8s.pod.label.data=` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.pod.name` | string | The name of the Pod. | `opentelemetry-pod-autoconf` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.pod.uid` | string | The UID of the Pod. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.replicaset.name` | string | The name of the ReplicaSet. | `opentelemetry` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.replicaset.uid` | string | The UID of the ReplicaSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.statefulset.name` | string | The name of the StatefulSet. | `opentelemetry` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.statefulset.uid` | string | The UID of the StatefulSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** K8s doesn't have support for obtaining a cluster ID. If this is ever +added, we will recommend collecting the `k8s.cluster.uid` through the +official APIs. In the meantime, we are able to use the `uid` of the +`kube-system` namespace as a proxy for cluster ID. Read on for the +rationale. + +Every object created in a K8s cluster is assigned a distinct UID. The +`kube-system` namespace is used by Kubernetes itself and will exist +for the lifetime of the cluster. Using the `uid` of the `kube-system` +namespace is a reasonable proxy for the K8s ClusterID as it will only +change if the cluster is rebuilt. Furthermore, Kubernetes UIDs are +UUIDs as standardized by +[ISO/IEC 9834-8 and ITU-T X.667](https://www.itu.int/ITU-T/studygroups/com17/oid.html). +Which states: + +> If generated according to one of the mechanisms defined in Rec. +> ITU-T X.667 | ISO/IEC 9834-8, a UUID is either guaranteed to be +> different from all other UUIDs generated before 3603 A.D., or is +> extremely likely to be different (depending on the mechanism chosen). + +Therefore, UIDs between clusters should be extremely unlikely to +conflict. + +## K8s Deprecated Attributes + +Describes deprecated k8s attributes. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------- | ------ | ---------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------- | +| `k8s.pod.labels.` | string | Deprecated, use `k8s.pod.label` instead. | `k8s.pod.label.app=my-app` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `k8s.pod.label`. | diff --git a/docs/attributes-registry/log.md b/docs/attributes-registry/log.md new file mode 100644 index 0000000000..e829babffd --- /dev/null +++ b/docs/attributes-registry/log.md @@ -0,0 +1,48 @@ + + + + + +# Log + +- [Log](#log-attributes) +- [Log File](#log-file-attributes) +- [Log Record](#log-record-attributes) + +## Log Attributes + +This document defines log attributes + +| Attribute | Type | Description | Examples | Stability | +| -------------- | ------ | ------------------------------------------------------------------------------ | ------------------ | ---------------------------------------------------------------- | +| `log.iostream` | string | The stream associated with the log. See below for a list of well-known values. | `stdout`; `stderr` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`log.iostream` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------- | ------------------------- | ---------------------------------------------------------------- | +| `stdout` | Logs from stdout stream | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `stderr` | Events from stderr stream | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Log File Attributes + +Attributes for a file to which log was emitted. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------ | ------ | -------------------------------------------------- | -------------------------- | ---------------------------------------------------------------- | +| `log.file.name` | string | The basename of the file. | `audit.log` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `log.file.name_resolved` | string | The basename of the file, with symlinks resolved. | `uuid.log` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `log.file.path` | string | The full path to the file. | `/var/log/mysql/audit.log` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `log.file.path_resolved` | string | The full path to the file, with symlinks resolved. | `/var/lib/docker/uuid.log` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Log Record Attributes + +This document defines the generic attributes that may be used in any Log Record. + +| Attribute | Type | Description | Examples | Stability | +| ---------------- | ------ | ------------------------------------------- | ---------------------------- | ---------------------------------------------------------------- | +| `log.record.uid` | string | A unique identifier for the Log Record. [1] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values. +The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), but other identifiers (e.g. UUID) may be used as needed. diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md new file mode 100644 index 0000000000..0ff400f546 --- /dev/null +++ b/docs/attributes-registry/messaging.md @@ -0,0 +1,185 @@ + + + + + +# Messaging + +- [Messaging](#messaging-attributes) +- [Messaging Deprecated](#messaging-deprecated-attributes) +- [Messaging Eventhubs](#messaging-eventhubs-attributes) +- [Messaging Gcp Pubsub](#messaging-gcp-pubsub-attributes) +- [Messaging Kafka](#messaging-kafka-attributes) +- [Messaging Rabbitmq](#messaging-rabbitmq-attributes) +- [Messaging Rocketmq](#messaging-rocketmq-attributes) +- [Messaging Servicebus](#messaging-servicebus-attributes) + +## Messaging Attributes + +Attributes describing telemetry around messaging systems and messaging activities. + +| Attribute | Type | Description | Examples | Stability | +| ----------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | ---------------------------------------------------------------- | +| `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.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.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.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.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.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 | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `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 +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]:** 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 +body size should be used. + +**[6]:** 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. + +`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 | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `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) | +| `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) | +| `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) | +| `process` | One or more messages are delivered to or processed by a consumer. | ![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 | +| ------------ | --------------------------------- | ---------------------------------------------------------------- | +| `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) | +| `servicebus` | Azure Service Bus | ![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) | +| `rabbitmq` | RabbitMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rocketmq` | Apache RocketMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Messaging Deprecated Attributes + +Describes deprecated messaging attributes. + +| Attribute | Type | Description | Examples | Stability | +| --------------------------------------- | ------ | ------------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------- | +| `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 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) | + +## Messaging Gcp Pubsub Attributes + +This group describes attributes specific to GCP Pub/Sub. + +| Attribute | Type | Description | Examples | Stability | +| ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------- | +| `messaging.gcp_pubsub.message.ack_deadline` | int | The ack deadline in seconds set for the modify ack deadline request. | `10` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.gcp_pubsub.message.ack_id` | string | The ack id for a given message. | `ack_id` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.gcp_pubsub.message.delivery_attempt` | int | The delivery attempt for a given message. | `2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.gcp_pubsub.message.ordering_key` | string | The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. | `ordering_key` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Messaging Kafka Attributes + +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. [8] | `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) | + +**[8]:** 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 + +This group describes attributes specific to RabbitMQ. + +| Attribute | Type | Description | Examples | Stability | +| -------------------------------------------- | ------ | ----------------------------- | -------- | ---------------------------------------------------------------- | +| `messaging.rabbitmq.destination.routing_key` | string | RabbitMQ message routing key. | `myKey` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.rabbitmq.message.delivery_tag` | int | RabbitMQ message delivery tag | `123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Messaging Rocketmq Attributes + +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) | +| `messaging.rocketmq.message.group` | 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.rocketmq.message.keys` | string[] | Key(s) of message, another way to mark message besides message id. | `keyA`; `keyB` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.rocketmq.message.tag` | string | The secondary classifier of message besides topic. | `tagA` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.rocketmq.message.type` | string | Type of message. | `normal`; `fifo`; `delay` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.rocketmq.namespace` | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`messaging.rocketmq.consumption_model` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------------- | ------------------------------ | ---------------------------------------------------------------- | +| `clustering` | Clustering consumption model | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `broadcasting` | Broadcasting consumption model | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`messaging.rocketmq.message.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------------- | ------------------- | ---------------------------------------------------------------- | +| `normal` | Normal message | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `fifo` | FIFO message | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `delay` | Delay message | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `transaction` | Transaction message | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Messaging Servicebus Attributes + +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) | + +`messaging.servicebus.disposition_status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------------- | ------------------------------------ | ---------------------------------------------------------------- | +| `complete` | Message is completed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `abandon` | Message is abandoned | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dead_letter` | Message is sent to dead letter queue | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `defer` | Message is deferred | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/network.md b/docs/attributes-registry/network.md new file mode 100644 index 0000000000..9d038e5e0a --- /dev/null +++ b/docs/attributes-registry/network.md @@ -0,0 +1,140 @@ + + + + + +# Network + +- [Network](#network-attributes) +- [Network Deprecated](#network-deprecated-attributes) + +## Network Attributes + +These attributes may be used for any network related operation. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------- | +| `network.carrier.icc` | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `network.carrier.mcc` | string | The mobile carrier country code. | `310` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `network.carrier.mnc` | string | The mobile carrier network code. | `001` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `network.carrier.name` | string | The name of the mobile carrier. | `sprint` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `network.connection.subtype` | string | This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. | `gprs`; `edge`; `umts` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `network.connection.type` | string | The internet connection type. | `wifi`; `wired`; `cell` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `network.io.direction` | string | The network IO operation direction. | `transmit`; `receive` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `network.local.address` | string | Local address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `network.local.port` | int | Local port number of the network connection. | `65123` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `network.peer.address` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `network.peer.port` | int | Peer port number of the network connection. | `65123` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `network.protocol.name` | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `amqp`; `http`; `mqtt` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `network.protocol.version` | string | The actual version of the protocol used for network communication. [2] | `1.1`; `2` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp`; `pipe` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `network.type` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** The value SHOULD be normalized to lowercase. +**[2]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. + +**[3]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[4]:** The value SHOULD be normalized to lowercase. + +`network.connection.subtype` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ---------------- | ----------------------------------- | ---------------------------------------------------------------- | +| `gprs` | GPRS | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `edge` | EDGE | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `umts` | UMTS | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cdma` | CDMA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `evdo_0` | EVDO Rel. 0 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `evdo_a` | EVDO Rev. A | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cdma2000_1xrtt` | CDMA2000 1XRTT | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hsdpa` | HSDPA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hsupa` | HSUPA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hspa` | HSPA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iden` | IDEN | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `evdo_b` | EVDO Rev. B | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `lte` | LTE | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ehrpd` | EHRPD | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hspap` | HSPAP | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gsm` | GSM | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `td_scdma` | TD-SCDMA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iwlan` | IWLAN | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nr` | 5G NR (New Radio) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nrnsa` | 5G NRNSA (New Radio Non-Standalone) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `lte_ca` | LTE CA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`network.connection.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------------- | ----------- | ---------------------------------------------------------------- | +| `wifi` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `wired` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cell` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unavailable` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unknown` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`network.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ---------- | ----------- | ---------------------------------------------------------------- | +| `transmit` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `receive` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------ | ------------------------ | ---------------------------------------------------------- | +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------ | ----------- | ---------------------------------------------------------- | +| `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +## Network Deprecated Attributes + +These attributes may be used for any network related operation. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------- | ------ | -------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `net.host.name` | string | Deprecated, use `server.address`. | `example.com` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `server.address`. | +| `net.host.port` | int | Deprecated, use `server.port`. | `8080` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `server.port`. | +| `net.peer.name` | string | Deprecated, use `server.address` on client spans and `client.address` on server spans. | `example.com` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `server.address` on client spans and `client.address` on server spans. | +| `net.peer.port` | int | Deprecated, use `server.port` on client spans and `client.port` on server spans. | `8080` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `server.port` on client spans and `client.port` on server spans. | +| `net.protocol.name` | string | Deprecated, use `network.protocol.name`. | `amqp`; `http`; `mqtt` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `network.protocol.name`. | +| `net.protocol.version` | string | Deprecated, use `network.protocol.version`. | `3.1.1` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `network.protocol.version`. | +| `net.sock.family` | string | Deprecated, use `network.transport` and `network.type`. | `inet`; `inet6`; `unix` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Split to `network.transport` and `network.type`. | +| `net.sock.host.addr` | string | Deprecated, use `network.local.address`. | `/var/my.sock` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `network.local.address`. | +| `net.sock.host.port` | int | Deprecated, use `network.local.port`. | `8080` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `network.local.port`. | +| `net.sock.peer.addr` | string | Deprecated, use `network.peer.address`. | `192.168.0.1` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `network.peer.address`. | +| `net.sock.peer.name` | string | Deprecated, no replacement at this time. | `/var/my.sock` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | +| `net.sock.peer.port` | int | Deprecated, use `network.peer.port`. | `65531` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `network.peer.port`. | +| `net.transport` | string | Deprecated, use `network.transport`. | `ip_tcp`; `ip_udp`; `pipe` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `network.transport`. | + +`net.sock.family` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------- | ----------------------- | ---------------------------------------------------------------- | +| `inet` | IPv4 address | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `inet6` | IPv6 address | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unix` | Unix domain socket path | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`net.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------- | ------------------------------ | ---------------------------------------------------------------- | +| `ip_tcp` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ip_udp` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pipe` | Named or anonymous pipe. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `inproc` | In-process communication. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other` | Something else (non IP-based). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/oci.md b/docs/attributes-registry/oci.md new file mode 100644 index 0000000000..b5102b7e7e --- /dev/null +++ b/docs/attributes-registry/oci.md @@ -0,0 +1,18 @@ + + + + + +# OCI + +## Oci Manifest Attributes + +An OCI image manifest. + +| Attribute | Type | Description | Examples | Stability | +| --------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `oci.manifest.digest` | string | The digest of the OCI image manifest. For container images specifically is the digest by which the container image is known. [1] | `sha256:e4ca62c0d62f3e886e684806dfe9d4e0cda60d54986898173c1083856cfda0f4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Follows [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md), and specifically the [Digest property](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests). +An example can be found in [Example Image Manifest](https://docs.docker.com/registry/spec/manifest-v2-2/#example-image-manifest). diff --git a/docs/attributes-registry/opentracing.md b/docs/attributes-registry/opentracing.md new file mode 100644 index 0000000000..83d11b4f4e --- /dev/null +++ b/docs/attributes-registry/opentracing.md @@ -0,0 +1,24 @@ + + + + + +# OpenTracing + +## Opentracing Attributes + +Attributes used by the OpenTracing Shim layer. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------- | ------ | ------------------------------- | -------------------------- | ---------------------------------------------------------------- | +| `opentracing.ref_type` | string | Parent-child Reference type [1] | `child_of`; `follows_from` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The causal relationship between a child Span and a parent Span. + +`opentracing.ref_type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `child_of` | The parent Span depends on the child Span in some capacity | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `follows_from` | The parent Span doesn't depend in any way on the result of the child Span | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/os.md b/docs/attributes-registry/os.md new file mode 100644 index 0000000000..a2ff3e6c4a --- /dev/null +++ b/docs/attributes-registry/os.md @@ -0,0 +1,35 @@ + + + + + +# OS + +## Os Attributes + +The operating system (OS) on which the process represented by this resource is running. + +| Attribute | Type | Description | Examples | Stability | +| ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------- | +| `os.build_id` | string | Unique identifier for a particular build or compilation of the operating system. | `TQ3C.230805.001.B2`; `20E247`; `22621` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `os.description` | string | Human readable (not intended to be parsed) OS version information, like e.g. reported by `ver` or `lsb_release -a` commands. | `Microsoft Windows [Version 10.0.18363.778]`; `Ubuntu 18.04.1 LTS` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `os.name` | string | Human readable operating system name. | `iOS`; `Android`; `Ubuntu` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `os.type` | string | The operating system type. | `windows`; `linux`; `darwin` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `os.version` | string | The version string of the operating system as defined in [Version Attributes](/docs/resource/README.md#version-attributes). | `14.2.1`; `18.04.1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`os.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------------- | ------------------------------------ | ---------------------------------------------------------------- | +| `windows` | Microsoft Windows | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `linux` | Linux | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `darwin` | Apple Darwin | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `freebsd` | FreeBSD | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `netbsd` | NetBSD | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `openbsd` | OpenBSD | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dragonflybsd` | DragonFly BSD | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hpux` | HP-UX (Hewlett Packard Unix) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aix` | AIX (Advanced Interactive eXecutive) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `solaris` | SunOS, Oracle Solaris | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `z_os` | IBM z/OS | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md new file mode 100644 index 0000000000..7bb1afb800 --- /dev/null +++ b/docs/attributes-registry/otel.md @@ -0,0 +1,45 @@ + + + + + +# OTel + +- [Otel](#otel-attributes) +- [Otel Library Deprecated](#otel-library-deprecated-attributes) +- [Otel Scope](#otel-scope-attributes) + +## Otel Attributes + +Attributes reserved for OpenTelemetry + +| Attribute | Type | Description | Examples | Stability | +| ------------------------- | ------ | -------------------------------------------------------------------------------------- | -------------------- | ---------------------------------------------------------- | +| `otel.status_code` | string | Name of the code, either "OK" or "ERROR". MUST NOT be set if the status code is UNSET. | `OK`; `ERROR` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `otel.status_description` | string | Description of the Status if it has a value, otherwise not set. | `resource not found` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`otel.status_code` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | +| `OK` | The operation has been validated by an Application developer or Operator to have completed successfully. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ERROR` | The operation contains an error. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +## Otel Library Deprecated Attributes + +Describes deprecated otel.library attributes. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------- | ------ | ----------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------ | +| `otel.library.name` | string | | `io.opentelemetry.contrib.mongodb` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
use the `otel.scope.name` attribute. | +| `otel.library.version` | string | | `1.0.0` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
use the `otel.scope.version` attribute. | + +## Otel Scope Attributes + +Attributes used by non-OTLP exporters to represent OpenTelemetry Scope's concepts. + +| Attribute | Type | Description | Examples | Stability | +| -------------------- | ------ | ------------------------------------------------------------------------------------ | ---------------------------------- | ---------------------------------------------------------- | +| `otel.scope.name` | string | The name of the instrumentation scope - (`InstrumentationScope.Name` in OTLP). | `io.opentelemetry.contrib.mongodb` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `otel.scope.version` | string | The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). | `1.0.0` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/attributes-registry/peer.md b/docs/attributes-registry/peer.md new file mode 100644 index 0000000000..69dd589473 --- /dev/null +++ b/docs/attributes-registry/peer.md @@ -0,0 +1,15 @@ + + + + + +# Peer + +## Peer Attributes + +Operations that access some remote service. + +| Attribute | Type | Description | Examples | Stability | +| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------- | +| `peer.service` | string | The [`service.name`](/docs/resource/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. | `AuthTokenCache` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/process.md b/docs/attributes-registry/process.md new file mode 100644 index 0000000000..0c46dd2e78 --- /dev/null +++ b/docs/attributes-registry/process.md @@ -0,0 +1,40 @@ + + + + + +# Process + +## Process Attributes + +An operating system process. + +| Attribute | Type | Description | Examples | Stability | +| ----------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------- | +| `process.command` | string | The command used to launch the process (i.e. the command name). On Linux based systems, can be set to the zeroth string in `proc/[pid]/cmdline`. On Windows, can be set to the first parameter extracted from `GetCommandLineW`. | `cmd/otelcol` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.command_args` | string[] | All the command arguments (including the command/executable itself) as received by the process. On Linux-based systems (and some other Unixoid systems supporting procfs), can be set according to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. For libc-based executables, this would be the full argv vector passed to `main`. | `cmd/otecol`; `--config=config.yaml` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.command_line` | string | The full command used to launch the process as a single string representing the full command. On Windows, can be set to the result of `GetCommandLineW`. Do not set this if you have to assemble it just for monitoring; use `process.command_args` instead. | `C:\cmd\otecol --config="my directory\config.yaml"` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.creation.time` | string | The date and time the process was created, in ISO 8601 format. | `2023-11-21T09:25:34.853Z` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.executable.name` | string | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.executable.path` | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.exit.code` | int | The exit code of the process. | `127` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.exit.time` | string | The date and time the process exited, in ISO 8601 format. | `2023-11-21T09:26:12.315Z` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.group_leader.pid` | int | The PID of the process's group leader. This is also the process group ID (PGID) of the process. | `23` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.interactive` | boolean | Whether the process is connected to an interactive shell. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.owner` | string | The username of the user that owns the process. | `root` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.parent_pid` | int | Parent Process identifier (PPID). | `111` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.pid` | int | Process identifier (PID). | `1234` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `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.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) | +| `process.session_leader.pid` | int | The PID of the process's session leader. This is also the session ID (SID) of the process. | `14` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.user.id` | int | The effective user ID (EUID) of the process. | `1001` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.user.name` | string | The username of the effective user of the process. | `root` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.vpid` | int | Virtual process identifier. [1] | `12` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The process ID within a PID namespace. This is not necessarily unique across all processes on the host but it is unique within the process namespace that the process exists within. diff --git a/docs/attributes-registry/rpc.md b/docs/attributes-registry/rpc.md new file mode 100644 index 0000000000..feaddc5927 --- /dev/null +++ b/docs/attributes-registry/rpc.md @@ -0,0 +1,125 @@ + + + + + +# RPC + +- [Rpc](#rpc-attributes) +- [Rpc Deprecated](#rpc-deprecated-attributes) + +## Rpc Attributes + +This document defines attributes for remote procedure calls. + +| Attribute | Type | Description | Examples | Stability | +| ----------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `rpc.connect_rpc.error_code` | string | The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. | `cancelled`; `unknown`; `invalid_argument` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.connect_rpc.request.metadata.` | string[] | Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. [1] | `rpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.connect_rpc.response.metadata.` | string[] | Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. [2] | `rpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.grpc.request.metadata.` | string[] | gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [3] | `rpc.grpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.grpc.response.metadata.` | string[] | gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [4] | `rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.grpc.status_code` | int | The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. | `0`; `1`; `2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.jsonrpc.error_code` | int | `error.code` property of response if it is an error response. | `-32700`; `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.jsonrpc.error_message` | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.jsonrpc.request_id` | string | `id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. | `10`; `request-7`; `` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.jsonrpc.version` | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. | `2.0`; `1.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.message.compressed_size` | int | Compressed size of the message in bytes. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.message.id` | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [5] | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.message.type` | string | Whether this is a received or sent message. | `SENT`; `RECEIVED` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.message.uncompressed_size` | int | Uncompressed size of the message in bytes. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [6] | `exampleMethod` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [7] | `myservice.EchoService` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc`; `java_rmi`; `dotnet_wcf` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + +**[2]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + +**[3]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + +**[4]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + +**[5]:** This way we guarantee that the values will be consistent between different implementations. +**[6]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[7]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +`rpc.connect_rpc.error_code` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --------------------- | ----------- | ---------------------------------------------------------------- | +| `cancelled` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unknown` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `invalid_argument` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `deadline_exceeded` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `not_found` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `already_exists` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `permission_denied` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `resource_exhausted` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `failed_precondition` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aborted` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `out_of_range` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unimplemented` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `internal` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unavailable` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `data_loss` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unauthenticated` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`rpc.grpc.status_code` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ----- | ------------------- | ---------------------------------------------------------------- | +| `0` | OK | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `1` | CANCELLED | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `2` | UNKNOWN | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `3` | INVALID_ARGUMENT | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `4` | DEADLINE_EXCEEDED | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `5` | NOT_FOUND | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `6` | ALREADY_EXISTS | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `7` | PERMISSION_DENIED | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `8` | RESOURCE_EXHAUSTED | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `9` | FAILED_PRECONDITION | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `10` | ABORTED | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `11` | OUT_OF_RANGE | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `12` | UNIMPLEMENTED | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `13` | INTERNAL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `14` | UNAVAILABLE | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `15` | DATA_LOSS | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `16` | UNAUTHENTICATED | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`rpc.message.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ---------- | ----------- | ---------------------------------------------------------------- | +| `SENT` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `RECEIVED` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------------- | ------------ | ---------------------------------------------------------------- | +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Rpc Deprecated Attributes + +Deprecated rpc message attributes. + +| Attribute | Type | Description | Examples | Stability | +| --------------------------- | ------ | -------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------- | +| `message.compressed_size` | int | Deprecated, use `rpc.message.compressed_size` instead. | | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `rpc.message.compressed_size`. | +| `message.id` | int | Deprecated, use `rpc.message.id` instead. | | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `rpc.message.id`. | +| `message.type` | string | Deprecated, use `rpc.message.type` instead. | `SENT`; `RECEIVED` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `rpc.message.type`. | +| `message.uncompressed_size` | int | Deprecated, use `rpc.message.uncompressed_size` instead. | | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `rpc.message.uncompressed_size`. | + +`message.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ---------- | ----------- | ---------------------------------------------------------------- | +| `SENT` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `RECEIVED` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/server.md b/docs/attributes-registry/server.md new file mode 100644 index 0000000000..d2994ae49a --- /dev/null +++ b/docs/attributes-registry/server.md @@ -0,0 +1,20 @@ + + + + + +# Server + +## Server Attributes + +These attributes may be used to describe the server in a connection-based network interaction where there is one side that initiates the connection (the client is the side that initiates the connection). This covers all TCP network interactions since TCP is connection-based and one side initiates the connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the protocol / API doesn't expose a clear notion of client and server). This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS. + +| Attribute | Type | Description | Examples | Stability | +| ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------- | +| `server.address` | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `server.port` | int | Server port number. [2] | `80`; `8080`; `443` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + +**[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. diff --git a/docs/attributes-registry/service.md b/docs/attributes-registry/service.md new file mode 100644 index 0000000000..6cbaf663b7 --- /dev/null +++ b/docs/attributes-registry/service.md @@ -0,0 +1,49 @@ + + + + + +# Service + +## Service Attributes + +A service instance. + +| Attribute | Type | Description | Examples | Stability | +| --------------------- | ------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------- | +| `service.instance.id` | string | The string ID of the service instance. [1] | `627cc493-f310-47de-96bd-71410b7dec09` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `service.name` | string | Logical name of the service. [2] | `shoppingcart` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `service.namespace` | string | A namespace for `service.name`. [3] | `Shop` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `service.version` | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words +`service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to +distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled +service). + +Implementations, such as SDKs, are recommended to generate a random Version 1 or Version 4 [RFC +4122](https://www.ietf.org/rfc/rfc4122.txt) UUID, but are free to use an inherent unique ID as the source of +this value if stability is desirable. In that case, the ID SHOULD be used as source of a UUID Version 5 and +SHOULD use the following UUID as the namespace: `4d63009a-8d0f-11ee-aad7-4c796ed8e320`. + +UUIDs are typically recommended, as only an opaque value for the purposes of identifying a service instance is +needed. Similar to what can be seen in the man page for the +[`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/machine-id.html) file, the underlying +data, such as pod name and namespace should be treated as confidential, being the user's choice to expose it +or not via another resource attribute. + +For applications running behind an application server (like unicorn), we do not recommend using one identifier +for all processes participating in the application. Instead, it's recommended each division (e.g. a worker +thread in unicorn) to have its own instance.id. + +It's not recommended for a Collector to set `service.instance.id` if it can't unambiguously determine the +service instance that is generating that telemetry. For instance, creating an UUID based on `pod.name` will +likely be wrong, as the Collector might not know from which container within that pod the telemetry originated. +However, Collectors can set the `service.instance.id` if they can unambiguously determine the service instance +for that telemetry. This is typically the case for scraping receivers, as they know the target address and +port. + +**[2]:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. + +**[3]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. diff --git a/docs/attributes-registry/session.md b/docs/attributes-registry/session.md new file mode 100644 index 0000000000..f17586ea09 --- /dev/null +++ b/docs/attributes-registry/session.md @@ -0,0 +1,18 @@ + + + + + +# Session + +## Session Attributes + +Session is defined as the period of time encompassing all activities performed by the application and the actions executed by the end user. +Consequently, a Session is represented as a collection of Logs, Events, and Spans emitted by the Client Application throughout the Session's duration. Each Session is assigned a unique identifier, which is included as an attribute in the Logs, Events, and Spans generated during the Session's lifecycle. +When a session reaches end of life, typically due to user inactivity or session timeout, a new session identifier will be assigned. The previous session identifier may be provided by the instrumentation so that telemetry backends can link the two sessions. + +| Attribute | Type | Description | Examples | Stability | +| --------------------- | ------ | ---------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------- | +| `session.id` | string | A unique id to identify a session. | `00112233-4455-6677-8899-aabbccddeeff` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `session.previous_id` | string | The previous `session.id` for this user, when known. | `00112233-4455-6677-8899-aabbccddeeff` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/signalr.md b/docs/attributes-registry/signalr.md new file mode 100644 index 0000000000..3bd984e04c --- /dev/null +++ b/docs/attributes-registry/signalr.md @@ -0,0 +1,32 @@ + + + + + +# SignalR + +## Signalr Attributes + +SignalR attributes + +| Attribute | Type | Description | Examples | Stability | +| --------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------- | +| `signalr.connection.status` | string | SignalR HTTP connection closure status. | `normal_closure`; `timeout`; `app_shutdown` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `signalr.transport` | string | [SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md) | `server_sent_events`; `long_polling`; `web_sockets` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`signalr.connection.status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ---------------- | ----------------------------------------------------------- | ---------------------------------------------------------- | +| `normal_closure` | The connection was closed normally. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `timeout` | The connection was closed due to a timeout. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `app_shutdown` | The connection was closed because the app is shutting down. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`signalr.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------------------- | ------------------------- | ---------------------------------------------------------- | +| `server_sent_events` | ServerSentEvents protocol | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `long_polling` | LongPolling protocol | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `web_sockets` | WebSockets protocol | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/attributes-registry/source.md b/docs/attributes-registry/source.md new file mode 100644 index 0000000000..abb52a5fdc --- /dev/null +++ b/docs/attributes-registry/source.md @@ -0,0 +1,18 @@ + + + + + +# Source + +## Source Attributes + +These attributes may be used to describe the sender of a network exchange/packet. These should be used when there is no client/server relationship between the two sides, or when that relationship is unknown. This covers low-level network interactions (e.g. packet tracing) where you don't know if there was a connection or which side initiated it. This also covers unidirectional UDP flows and peer-to-peer communication where the "user-facing" surface of the protocol / API doesn't expose a clear notion of client and server. + +| Attribute | Type | Description | Examples | Stability | +| ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------- | +| `source.address` | string | Source address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `source.example.com`; `10.1.2.80`; `/tmp/my.sock` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `source.port` | int | Source port number | `3389`; `2888` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** When observed from the destination side, and when communicating through an intermediary, `source.address` SHOULD represent the source address behind any intermediaries, for example proxies, if it's available. diff --git a/docs/attributes-registry/system.md b/docs/attributes-registry/system.md new file mode 100644 index 0000000000..180d62d803 --- /dev/null +++ b/docs/attributes-registry/system.md @@ -0,0 +1,183 @@ + + + + + +# System + +- [System](#system-attributes) +- [System Cpu](#system-cpu-attributes) +- [System Deprecated](#system-deprecated-attributes) +- [System Filesystem](#system-filesystem-attributes) +- [System Memory](#system-memory-attributes) +- [System Network](#system-network-attributes) +- [System Paging](#system-paging-attributes) +- [System Process](#system-process-attributes) + +## System Attributes + +Describes System attributes + +| Attribute | Type | Description | Examples | Stability | +| --------------- | ------ | --------------------- | -------------- | ---------------------------------------------------------------- | +| `system.device` | string | The device identifier | `(identifier)` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## 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 | `user`; `system`; `nice` | ![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. + +| Value | Description | Stability | +| ----------- | ----------- | ---------------------------------------------------------------- | +| `user` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nice` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `idle` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iowait` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interrupt` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `steal` | none | ![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`; `sleeping`; `stopped` | ![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 | +| ---------- | ----------- | ---------------------------------------------------------------- | +| `running` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `sleeping` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `stopped` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `defunct` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## System Filesystem Attributes + +Describes Filesystem attributes + +| Attribute | Type | Description | Examples | Stability | +| ------------------------------ | ------ | ------------------------- | -------------------------- | ---------------------------------------------------------------- | +| `system.filesystem.mode` | string | The filesystem mode | `rw, ro` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system.filesystem.mountpoint` | string | The filesystem mount path | `/mnt/data` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system.filesystem.state` | string | The filesystem state | `used`; `free`; `reserved` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system.filesystem.type` | string | The filesystem type | `fat32`; `exfat`; `ntfs` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.filesystem.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ---------- | ----------- | ---------------------------------------------------------------- | +| `used` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `free` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `reserved` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.filesystem.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --------- | ----------- | ---------------------------------------------------------------- | +| `fat32` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `exfat` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ntfs` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `refs` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hfsplus` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ext4` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## System Memory Attributes + +Describes System Memory attributes + +| Attribute | Type | Description | Examples | Stability | +| --------------------- | ------ | ---------------- | ------------------------ | ---------------------------------------------------------------- | +| `system.memory.state` | string | The memory state | `used`; `free`; `shared` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.memory.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `used` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `free` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `shared` | none | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed, report shared memory usage with `metric.system.memory.shared` metric | +| `buffers` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cached` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## System Network Attributes + +Describes Network attributes + +| Attribute | Type | Description | Examples | Stability | +| ---------------------- | ------ | ------------------------------------------------ | -------------------------------- | ---------------------------------------------------------------- | +| `system.network.state` | string | A stateless protocol MUST NOT set this attribute | `close`; `close_wait`; `closing` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.network.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------------- | ----------- | ---------------------------------------------------------------- | +| `close` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `close_wait` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `closing` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `delete` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `established` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `fin_wait_1` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `fin_wait_2` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `last_ack` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `listen` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `syn_recv` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `syn_sent` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `time_wait` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## System Paging Attributes + +Describes System Memory Paging attributes + +| Attribute | Type | Description | Examples | Stability | +| ------------------------- | ------ | --------------------------- | ---------------- | ---------------------------------------------------------------- | +| `system.paging.direction` | string | The paging access direction | `in`; `out` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system.paging.state` | string | The memory paging state | `used`; `free` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system.paging.type` | string | The memory paging type | `major`; `minor` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.paging.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ----- | ----------- | ---------------------------------------------------------------- | +| `in` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `out` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.paging.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------ | ----------- | ---------------------------------------------------------------- | +| `used` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `free` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.paging.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------- | ----------- | ---------------------------------------------------------------- | +| `major` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `minor` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## System Process Attributes + +Describes System Process attributes + +| Attribute | Type | Description | Examples | Stability | +| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ---------------------------------------------------------------- | +| `system.process.status` | string | The process state, e.g., [Linux Process State Codes](https://man7.org/linux/man-pages/man1/ps.1.html#PROCESS_STATE_CODES) | `running`; `sleeping`; `stopped` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.process.status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ---------- | ----------- | ---------------------------------------------------------------- | +| `running` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `sleeping` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `stopped` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `defunct` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/telemetry.md b/docs/attributes-registry/telemetry.md new file mode 100644 index 0000000000..bb46108eb6 --- /dev/null +++ b/docs/attributes-registry/telemetry.md @@ -0,0 +1,46 @@ + + + + + +# Telemetry + +## Telemetry Attributes + +This document defines attributes for telemetry SDK. + +| Attribute | Type | Description | Examples | Stability | +| -------------------------- | ------ | ------------------------------------------------------------------------------ | ------------------------- | ---------------------------------------------------------------- | +| `telemetry.distro.name` | string | The name of the auto instrumentation agent or distribution, if used. [1] | `parts-unlimited-java` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.distro.version` | string | The version string of the auto instrumentation agent or distribution, if used. | `1.2.3` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.language` | string | The language of the telemetry SDK. | `cpp`; `dotnet`; `erlang` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [2] | `opentelemetry` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Official auto instrumentation agents and distributions SHOULD set the `telemetry.distro.name` attribute to +a string starting with `opentelemetry-`, e.g. `opentelemetry-java-instrumentation`. + +**[2]:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. +If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the +`telemetry.sdk.name` attribute to the fully-qualified class or module name of this SDK's main entry point +or another suitable identifier depending on the language. +The identifier `opentelemetry` is reserved and MUST NOT be used in this case. +All custom identifiers SHOULD be stable across different versions of an implementation. + +`telemetry.sdk.language` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------- | ----------- | ---------------------------------------------------------- | +| `cpp` | none | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `dotnet` | none | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `erlang` | none | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `go` | none | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `java` | none | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `nodejs` | none | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `php` | none | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `python` | none | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ruby` | none | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `rust` | none | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `swift` | none | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `webjs` | none | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/attributes-registry/thread.md b/docs/attributes-registry/thread.md new file mode 100644 index 0000000000..c09ca1d632 --- /dev/null +++ b/docs/attributes-registry/thread.md @@ -0,0 +1,16 @@ + + + + + +# Thread + +## Thread Attributes + +These attributes may be used for any operation to store information about a thread that started a span. + +| Attribute | Type | Description | Examples | Stability | +| ------------- | ------ | --------------------------------------------------------- | -------- | ---------------------------------------------------------------- | +| `thread.id` | int | Current "managed" thread ID (as opposed to OS thread ID). | `42` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `thread.name` | string | Current thread name. | `main` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/tls.md b/docs/attributes-registry/tls.md new file mode 100644 index 0000000000..32a4fb4506 --- /dev/null +++ b/docs/attributes-registry/tls.md @@ -0,0 +1,52 @@ + + + + + +# TLS + +## Tls Attributes + +This document defines semantic convention attributes in the TLS namespace. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `tls.cipher` | string | String indicating the [cipher](https://datatracker.ietf.org/doc/html/rfc5246#appendix-A.5) used during the current connection. [1] | `TLS_RSA_WITH_3DES_EDE_CBC_SHA`; `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.client.certificate` | string | PEM-encoded stand-alone certificate offered by the client. This is usually mutually-exclusive of `client.certificate_chain` since this value also exists in that list. | `MII...` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.client.certificate_chain` | string[] | Array of PEM-encoded certificates that make up the certificate chain offered by the client. This is usually mutually-exclusive of `client.certificate` since that value should be the first certificate in the chain. | `MII...`; `MI...` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.client.hash.md5` | string | Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash. | `0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.client.hash.sha1` | string | Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash. | `9E393D93138888D288266C2D915214D1D1CCEB2A` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.client.hash.sha256` | string | Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash. | `0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.client.issuer` | string | Distinguished name of [subject](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.6) of the issuer of the x.509 certificate presented by the client. | `CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.client.ja3` | string | A hash that identifies clients based on how they perform an SSL/TLS handshake. | `d4e5b18d6b55c71272893221c96ba240` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.client.not_after` | string | Date/Time indicating when client certificate is no longer considered valid. | `2021-01-01T00:00:00.000Z` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.client.not_before` | string | Date/Time indicating when client certificate is first considered valid. | `1970-01-01T00:00:00.000Z` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.client.server_name` | string | Also called an SNI, this tells the server which hostname to which the client is attempting to connect to. | `opentelemetry.io` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.client.subject` | string | Distinguished name of subject of the x.509 certificate presented by the client. | `CN=myclient, OU=Documentation Team, DC=example, DC=com` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.client.supported_ciphers` | string[] | Array of ciphers offered by the client during the client hello. | `"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", "..."` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.curve` | string | String indicating the curve used for the given cipher, when applicable | `secp256r1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.established` | boolean | Boolean flag indicating if the TLS negotiation was successful and transitioned to an encrypted tunnel. | `true` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.next_protocol` | string | String indicating the protocol being tunneled. Per the values in the [IANA registry](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids), this string should be lower case. | `http/1.1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.protocol.name` | string | Normalized lowercase protocol name parsed from original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) | `ssl`; `tls` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.protocol.version` | string | Numeric part of the version parsed from the original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) | `1.2`; `3` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.resumed` | boolean | Boolean flag indicating if this TLS connection was resumed from an existing TLS negotiation. | `true` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.server.certificate` | string | PEM-encoded stand-alone certificate offered by the server. This is usually mutually-exclusive of `server.certificate_chain` since this value also exists in that list. | `MII...` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.server.certificate_chain` | string[] | Array of PEM-encoded certificates that make up the certificate chain offered by the server. This is usually mutually-exclusive of `server.certificate` since that value should be the first certificate in the chain. | `MII...`; `MI...` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.server.hash.md5` | string | Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash. | `0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.server.hash.sha1` | string | Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash. | `9E393D93138888D288266C2D915214D1D1CCEB2A` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.server.hash.sha256` | string | Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash. | `0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.server.issuer` | string | Distinguished name of [subject](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.6) of the issuer of the x.509 certificate presented by the client. | `CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.server.ja3s` | string | A hash that identifies servers based on how they perform an SSL/TLS handshake. | `d4e5b18d6b55c71272893221c96ba240` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.server.not_after` | string | Date/Time indicating when server certificate is no longer considered valid. | `2021-01-01T00:00:00.000Z` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.server.not_before` | string | Date/Time indicating when server certificate is first considered valid. | `1970-01-01T00:00:00.000Z` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls.server.subject` | string | Distinguished name of subject of the x.509 certificate presented by the server. | `CN=myserver, OU=Documentation Team, DC=example, DC=com` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The values allowed for `tls.cipher` MUST be one of the `Descriptions` of the [registered TLS Cipher Suits](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#table-tls-parameters-4). + +`tls.protocol.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ----- | ----------- | ---------------------------------------------------------------- | +| `ssl` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls` | none | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/url.md b/docs/attributes-registry/url.md new file mode 100644 index 0000000000..3594692af9 --- /dev/null +++ b/docs/attributes-registry/url.md @@ -0,0 +1,47 @@ + + + + + +# URL + +## Url Attributes + +Attributes describing URL. + +| Attribute | Type | Description | Examples | Stability | +| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `url.domain` | string | Domain extracted from the `url.full`, such as "opentelemetry.io". [1] | `www.foo.bar`; `opentelemetry.io`; `3.12.167.2`; `[1080:0:0:0:8:800:200C:417A]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `url.extension` | string | The file extension extracted from the `url.full`, excluding the leading dot. [2] | `png`; `gz` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `url.fragment` | string | The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component | `SemConv` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [3] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `url.original` | string | Unmodified original URL as seen in the event source. [4] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `search?q=OpenTelemetry` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `url.path` | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [5] | `/search` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `url.port` | int | Port extracted from the `url.full` | `443` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `url.query` | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [6] | `q=OpenTelemetry` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `url.registered_domain` | string | The highest registered url domain, stripped of the subdomain. [7] | `example.com`; `foo.co.uk` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `url.subdomain` | string | The subdomain portion of a fully qualified domain name includes all of the names except the host name under the registered_domain. In a partially qualified domain, or if the qualification level of the full name cannot be determined, subdomain contains all of the names below the registered domain. [8] | `east`; `sub2.sub1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `url.top_level_domain` | string | The effective top level domain (eTLD), also known as the domain suffix, is the last part of the domain name. For example, the top level domain for example.com is `com`. [9] | `com`; `co.uk` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** In some cases a URL may refer to an IP and/or port directly, without a domain name. In this case, the IP address would go to the domain field. If the URL contains a [literal IPv6 address](https://www.rfc-editor.org/rfc/rfc2732#section-2) enclosed by `[` and `]`, the `[` and `]` characters should also be captured in the domain field. + +**[2]:** The file extension is only set if it exists, as not every url has a file extension. When the file name has multiple extensions `example.tar.gz`, only the last one should be captured `gz`, not `tar.gz`. + +**[3]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. +`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. + +**[4]:** In network monitoring, the observed URL may be a full URL, whereas in access logs, the URL is often just represented as a path. This field is meant to represent the URL as it was observed, complete or not. +`url.original` might contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case password and username SHOULD NOT be redacted and attribute's value SHOULD remain the same. + +**[5]:** Sensitive content provided in `url.path` SHOULD be scrubbed when instrumentations can identify it. + +**[6]:** Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it. + +**[7]:** This value can be determined precisely with the [public suffix list](http://publicsuffix.org). For example, the registered domain for `foo.example.com` is `example.com`. Trying to approximate this by simply taking the last two labels will not work well for TLDs such as `co.uk`. + +**[8]:** The subdomain portion of `www.east.mydomain.co.uk` is `east`. If the domain has multiple levels of subdomain, such as `sub2.sub1.example.com`, the subdomain field should contain `sub2.sub1`, with no trailing period. + +**[9]:** This value can be determined precisely with the [public suffix list](http://publicsuffix.org). diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md new file mode 100644 index 0000000000..34b0c71f89 --- /dev/null +++ b/docs/attributes-registry/user-agent.md @@ -0,0 +1,21 @@ + + + + + +# User Agent + +## User Agent Attributes + +Describes user-agent attributes. + +| Attribute | Type | Description | Examples | Stability | +| --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `user_agent.name` | string | Name of the user-agent extracted from original. Usually refers to the browser's name. [1] | `Safari`; `YourApp` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `user_agent.original` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1`; `YourApp/1.0.0 grpc-java-okhttp/1.27.2` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `user_agent.version` | string | Version of the user-agent extracted from original. Usually refers to the browser's version [2] | `14.1.2`; `1.0.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** [Example](https://www.whatsmyua.info) of extracting browser's name from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant name SHOULD be selected. In such a scenario it should align with `user_agent.version` + +**[2]:** [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant version SHOULD be selected. In such a scenario it should align with `user_agent.name` diff --git a/docs/attributes-registry/webengine.md b/docs/attributes-registry/webengine.md new file mode 100644 index 0000000000..be5955444e --- /dev/null +++ b/docs/attributes-registry/webengine.md @@ -0,0 +1,17 @@ + + + + + +# Webengine + +## Webengine Attributes + +This document defines the attributes used to describe the packaged software running the application code. + +| Attribute | Type | Description | Examples | Stability | +| ----------------------- | ------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `webengine.description` | string | Additional description of the web engine (e.g. detailed version and edition information). | `WildFly Full 21.0.0.Final (WildFly Core 13.0.1.Final) - 2.2.2.Final` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `webengine.name` | string | The name of the web engine. | `WildFly` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `webengine.version` | string | The version of the web engine. | `21.0.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/cloud-providers/README.md b/docs/cloud-providers/README.md index d9d43accec..863836b98d 100644 --- a/docs/cloud-providers/README.md +++ b/docs/cloud-providers/README.md @@ -1,7 +1,7 @@ @@ -15,4 +15,4 @@ Semantic conventions exist for the following cloud provider SDKs: - [AWS SDK](aws-sdk.md): Semantic Conventions for the _AWS SDK_. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md index 2c4d0ae012..e5374766b8 100644 --- a/docs/cloud-providers/aws-sdk.md +++ b/docs/cloud-providers/aws-sdk.md @@ -25,16 +25,26 @@ with the naming guidelines for RPC client spans. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.request_id` | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | Recommended | -| [`rpc.method`](../rpc/rpc-spans.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | Recommended | -| [`rpc.service`](../rpc/rpc-spans.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | Recommended | -| [`rpc.system`](../rpc/rpc-spans.md) | string | The value `aws-api`. | `aws-api` | Required | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). **[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -45,4 +55,4 @@ The following Semantic Conventions extend the general AWS SDK attributes for spe - [AWS DynamoDB](/docs/database/dynamodb.md): Semantic Conventions for _AWS DynamoDB_. - [AWS S3](/docs/object-stores/s3.md): Semantic Conventions for _AWS S3_. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/cloudevents/README.md b/docs/cloudevents/README.md index b6d66070c9..e97a44c391 100644 --- a/docs/cloudevents/README.md +++ b/docs/cloudevents/README.md @@ -1,7 +1,7 @@ @@ -15,4 +15,4 @@ Semantic conventions for CloudEvents are defined for the following signals: - [CloudEvents Spans](cloudevents-spans.md): Semantic Conventions for modeling CloudEvents as _spans_. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md index d13a8d5300..31193046c1 100644 --- a/docs/cloudevents/cloudevents-spans.md +++ b/docs/cloudevents/cloudevents-spans.md @@ -13,10 +13,10 @@ linkTitle: CloudEvents Spans - [Definitions](#definitions) - [Overview](#overview) - [Conventions](#conventions) - * [Spans](#spans) - + [Creation](#creation) - + [Processing](#processing) - * [Attributes](#attributes) + - [Spans](#spans) + - [Creation](#creation) + - [Processing](#processing) + - [Attributes](#attributes) @@ -40,7 +40,7 @@ document. A CloudEvent can be sent directly from producer to consumer. For such a scenario, the traditional parent-child trace model works well. However, CloudEvents are also used in distributed systems where an event -can go through many [hops]() +can go through many [hops](https://en.wikipedia.org/wiki/Hop_%28networking%29) until it reaches a consumer. In this scenario, the traditional parent-child trace model is not sufficient to produce a meaningful trace. @@ -200,14 +200,14 @@ The following attributes are applicable to creation and processing Spans. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event. | `123e4567-e89b-12d3-a456-426614174000`; `0001` | Required | -| `cloudevents.event_source` | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | Required | -| `cloudevents.event_spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses. | `1.0` | Recommended | -| `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | Recommended | -| `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`cloudevents.event_id`](/docs/attributes-registry/cloudevents.md) | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event. | `123e4567-e89b-12d3-a456-426614174000`; `0001` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`cloudevents.event_source`](/docs/attributes-registry/cloudevents.md) | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`cloudevents.event_spec_version`](/docs/attributes-registry/cloudevents.md) | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses. | `1.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`cloudevents.event_subject`](/docs/attributes-registry/cloudevents.md) | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`cloudevents.event_type`](/docs/attributes-registry/cloudevents.md) | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/database/README.md b/docs/database/README.md index 69b0ccf1f9..6222376394 100644 --- a/docs/database/README.md +++ b/docs/database/README.md @@ -1,7 +1,7 @@ @@ -12,6 +12,13 @@ path_base_for_github_subdir: This document defines semantic conventions for database client spans as well as database metrics and logs. +> **Warning** +> Existing database instrumentations that are using +> [v1.24.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/README.md) +> (or prior) SHOULD NOT change the version of the database conventions that they emit +> 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. + Semantic conventions for database operations are defined for the following signals: * [DB Spans](database-spans.md): Semantic Conventions for database client *spans*. @@ -24,11 +31,10 @@ Technology specific semantic conventions are defined for the following databases * [Cosmos DB](cosmosdb.md): Semantic Conventions for *Microsoft Cosmos DB*. * [CouchDB](couchdb.md): Semantic Conventions for *CouchDB*. * [Elasticsearch](elasticsearch.md): Semantic Conventions for *Elasticsearch*. -* [GraphQL](graphql.md): Semantic Conventions for *GraphQL Server*. * [HBase](hbase.md): Semantic Conventions for *HBase*. * [MongoDB](mongodb.md): Semantic Conventions for *MongoDB*. * [MSSQL](mssql.md): Semantic Conventions for *MSSQL*. * [Redis](redis.md): Semantic Conventions for *Redis*. * [SQL](sql.md): Semantic Conventions for *SQL* databases. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index fc420a9f5d..c83fb73b9a 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -12,39 +12,45 @@ described on this page. `db.system` MUST be set to `"cassandra"`. -## Call-level attributes - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `db.cassandra.page_size` | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` | Recommended | -| `db.cassandra.consistency_level` | string | The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). | `all` | Recommended | -| `db.cassandra.table` | string | The name of the primary table that the operation is acting upon, including the keyspace name (if applicable). [1] | `mytable` | Recommended | -| `db.cassandra.idempotence` | boolean | Whether or not the query is idempotent. | | Recommended | -| `db.cassandra.speculative_execution_count` | int | The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. | `0`; `2` | Recommended | -| `db.cassandra.coordinator.id` | string | The ID of the coordinating node for a query. | `be13faa2-8574-4d71-926d-27f16cf8a7af` | Recommended | -| `db.cassandra.coordinator.dc` | string | The data center of the coordinating node for a query. | `us-west-2` | Recommended | -| [`db.name`](database-spans.md) | string | The keyspace name in Cassandra. [2] | `mykeyspace` | Conditionally Required: If applicable. | - -**[1]:** This mirrors the db.sql.table attribute but references cassandra rather than sql. It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set. - -**[2]:** For Cassandra the `db.name` should be set to the Cassandra keyspace name. - -`db.cassandra.consistency_level` MUST be one of the following: - -| Value | Description | -|---|---| -| `all` | all | -| `each_quorum` | each_quorum | -| `quorum` | quorum | -| `local_quorum` | local_quorum | -| `one` | one | -| `two` | two | -| `three` | three | -| `local_one` | local_one | -| `any` | any | -| `serial` | serial | -| `local_serial` | local_serial | +## Attributes + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of the Cassandra table that the operation is acting upon. [1] | `public.users`; `customers` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The Cassandra keyspace name. [3] | `mykeyspace` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cassandra.consistency_level`](/docs/attributes-registry/db.md) | string | The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). | `all`; `each_quorum`; `quorum` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cassandra.coordinator.dc`](/docs/attributes-registry/db.md) | string | The data center of the coordinating node for a query. | `us-west-2` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cassandra.coordinator.id`](/docs/attributes-registry/db.md) | string | The ID of the coordinating node for a query. | `be13faa2-8574-4d71-926d-27f16cf8a7af` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cassandra.idempotence`](/docs/attributes-registry/db.md) | boolean | Whether or not the query is idempotent. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cassandra.page_size`](/docs/attributes-registry/db.md) | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cassandra.speculative_execution_count`](/docs/attributes-registry/db.md) | int | The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. | `0`; `2` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [4] | `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) | + +**[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. + +**[2]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.collection.name`, then it SHOULD be the first collection name found in the query. + +**[3]:** For commands that switch the keyspace, this SHOULD be set to the target keyspace (even if the command fails). + +**[4]:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. + +`db.cassandra.consistency_level` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `all` | all | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `each_quorum` | each_quorum | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `quorum` | quorum | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `local_quorum` | local_quorum | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `one` | one | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `two` | two | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `three` | three | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `local_one` | local_one | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `any` | any | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `serial` | serial | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `local_serial` | local_serial | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 83425d15bb..80ea0bc7a9 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -11,59 +11,57 @@ extend and override the [Database Semantic Conventions](database-spans.md) that describe common database operations attributes in addition to the Semantic Conventions described on this page. -## Call-level attributes +## Attributes `db.system` MUST be set to `"cosmosdb"`. Cosmos DB instrumentation includes call-level (public API) surface spans and network spans. Depending on the connection mode (Gateway or Direct), network-level spans may also be created. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `db.cosmosdb.client_id` | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | Recommended | -| `db.cosmosdb.operation_type` | string | CosmosDB Operation Type. | `Invalid` | Conditionally Required: [1] | -| `db.cosmosdb.connection_mode` | string | Cosmos client connection mode. | `gateway` | Conditionally Required: if not `direct` (or pick gw as default) | -| `db.cosmosdb.container` | string | Cosmos DB container name. | `anystring` | Conditionally Required: if available | -| `db.cosmosdb.request_content_length` | int | Request payload size in bytes | | Recommended | -| `db.cosmosdb.status_code` | int | Cosmos DB status code. | `200`; `201` | Conditionally Required: if response was received | -| `db.cosmosdb.sub_status_code` | int | Cosmos DB sub status code. | `1000`; `1002` | Conditionally Required: [2] | -| `db.cosmosdb.request_charge` | double | RU consumed for that operation | `46.18`; `1.0` | Conditionally Required: when available | -| `user_agent.original` | string | Full user-agent string is generated by Cosmos DB SDK [3] | `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 | - -**[1]:** when performing one of the operations in this list - -**[2]:** when response was received and contained sub-code. - -**[3]:** The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | Cosmos DB container name. [1] | `public.users`; `customers` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.connection_mode`](/docs/attributes-registry/db.md) | string | Cosmos client connection mode. | `gateway`; `direct` | `Conditionally Required` if not `direct` (or pick gw as default) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.operation_type`](/docs/attributes-registry/db.md) | string | CosmosDB Operation Type. | `Invalid`; `Create`; `Patch` | `Conditionally Required` when performing one of the operations in this list | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.request_charge`](/docs/attributes-registry/db.md) | double | RU consumed for that operation | `46.18`; `1` | `Conditionally Required` when available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB status code. | `200`; `201` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` when response was received and contained sub-code. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.client_id`](/docs/attributes-registry/db.md) | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.request_content_length`](/docs/attributes-registry/db.md) | int | Request payload size in bytes | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [2] | `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) | + +**[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. + +**[2]:** The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled. Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it). Default value is "NS". -`db.cosmosdb.operation_type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. - -| Value | Description | -|---|---| -| `Invalid` | invalid | -| `Create` | create | -| `Patch` | patch | -| `Read` | read | -| `ReadFeed` | read_feed | -| `Delete` | delete | -| `Replace` | replace | -| `Execute` | execute | -| `Query` | query | -| `Head` | head | -| `HeadFeed` | head_feed | -| `Upsert` | upsert | -| `Batch` | batch | -| `QueryPlan` | query_plan | -| `ExecuteJavaScript` | execute_javascript | - -`db.cosmosdb.connection_mode` MUST be one of the following: - -| Value | Description | -|---|---| -| `gateway` | Gateway (HTTP) connections mode | -| `direct` | Direct connection. | +`db.cosmosdb.connection_mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `gateway` | Gateway (HTTP) connections mode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `direct` | Direct connection. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`db.cosmosdb.operation_type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `Invalid` | invalid | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Create` | create | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Patch` | patch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Read` | read | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ReadFeed` | read_feed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Delete` | delete | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Replace` | replace | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Execute` | execute | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Query` | query | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Head` | head | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `HeadFeed` | head_feed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Upsert` | upsert | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Batch` | batch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `QueryPlan` | query_plan | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ExecuteJavaScript` | execute_javascript | ![Experimental](https://img.shields.io/badge/-experimental-blue) | In addition to Cosmos DB attributes, all spans include @@ -73,21 +71,21 @@ In addition to Cosmos DB attributes, all spans include | Key | Value | |:-------------------------------------| :------------------- | -| Span name | `"ReadItemsAsync"` | +| Span name | `"ReadItemsAsync orders"` | | `kind` | `"internal"` | | `az.namespace` | `"Microsoft.DocumentDB"` | | `db.system` | `"cosmosdb"` | -| `db.name` | `"database name"` | -| `db.operation` | `"ReadItemsAsync"` | -| `server.address` | `"account.documents.azure.com"` | +| `db.collection.name` | `"orders"` | +| `db.namespace` | `"ShopDb"` | +| `db.operation.name` | `"ReadItemsAsync"` | +| `server.address` | `"account.documents.azure.com"` | | `db.cosmosdb.client_id` | `3ba4827d-4422-483f-b59f-85b74211c11d` | | `db.cosmosdb.operation_type` | `Read` | | `user_agent.original` | `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\|` | | `db.cosmosdb.connection_mode` | `"Direct"` | -| `db.cosmosdb.container` | `"container name"` | | `db.cosmosdb.request_content_length` | `20` | | `db.cosmosdb.status_code` | `201` | | `db.cosmosdb.sub_status_code` | `0` | | `db.cosmosdb.request_charge` | `7.43` | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index 3624e69e9c..f520448637 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -12,14 +12,16 @@ described on this page. `db.system` MUST be set to `"couchdb"`. -## Call-level attributes +## Attributes - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`db.operation`](database-spans.md) | string | The HTTP method + the target REST route. [1] | `GET /{db}/{docid}` | Conditionally Required: If `db.statement` is not applicable. | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The HTTP method + the target REST route. [1] | `GET /{db}/{docid}` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** In **CouchDB**, `db.operation` should be set to the HTTP method + the target REST route according to the API reference documentation. For example, when retrieving a document, `db.operation` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`](http://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid). +**[1]:** In **CouchDB**, `db.operation.name` should be set to the HTTP method + the target REST route according to the API reference documentation. For example, when retrieving a document, `db.operation.name` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`](https://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid). + +**[2]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 7a24a76e98..4350081a1d 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -8,56 +8,307 @@ linkTitle: Metrics The conventions described in this section are specific to SQL and NoSQL clients. -**Disclaimer:** These are initial database client metric instruments and attributes but more may be added in the future. +**Disclaimer:** These are initial database client metric instruments +and attributes but more may be added in the future. -- [Metric Instruments](#metric-instruments) - * [Connection pools](#connection-pools) +- [Database operation](#database-operation) + - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) +- [Connection pools](#connection-pools) + - [Metric: `db.client.connection.count`](#metric-dbclientconnectioncount) + - [Metric: `db.client.connection.idle.max`](#metric-dbclientconnectionidlemax) + - [Metric: `db.client.connection.idle.min`](#metric-dbclientconnectionidlemin) + - [Metric: `db.client.connection.max`](#metric-dbclientconnectionmax) + - [Metric: `db.client.connection.pending_requests`](#metric-dbclientconnectionpending_requests) + - [Metric: `db.client.connection.timeouts`](#metric-dbclientconnectiontimeouts) + - [Metric: `db.client.connection.create_time`](#metric-dbclientconnectioncreate_time) + - [Metric: `db.client.connection.wait_time`](#metric-dbclientconnectionwait_time) + - [Metric: `db.client.connection.use_time`](#metric-dbclientconnectionuse_time) -## Metric Instruments +> **Warning** +> Existing database instrumentations that are using +> [v1.24.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md) +> (or prior) SHOULD NOT change the version of the database conventions that they emit +> 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. -The following metric instruments MUST be used to describe database client operations. They MUST be of the specified type -and units. +## Database operation -### Connection pools +### Metric: `db.client.operation.duration` -Below is a table of database client connection pool metric instruments that MUST be used by connection pool -instrumentations: +**Status**: [Experimental][DocumentStatus] + +This metric is [required][MetricRequired]. + +When this metric is reported alongside a database operation span, the metric value SHOULD be the same as the database operation span duration. + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/metrics/api.md#instrument-advisory-parameters) +of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.client.operation.duration` | Histogram | `s` | Duration of database client operations. | ![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 | +|---|---|---|---|---|---| +| [`db.system`](/docs/attributes-registry/db.md) | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql`; `mssql`; `mssqlcompact` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [3] | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [4] | ![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) | +| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [8] | `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. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. + +**[2]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.collection.name`, then it SHOULD be the first collection name found in the query. + +**[3]:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid. +Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. + +**[4]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. + +**[5]:** The `error.type` SHOULD match the error code returned by the database 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. + +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[7]:** If using a port other than the default port for this DBMS and if `server.address` is set. + +**[8]:** 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. + +**[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. + +`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 | +|---|---|---| +| `other_sql` | Some other SQL database. Fallback only. See notes. | ![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) | +| `oracle` | Oracle Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db2` | IBM Db2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `postgresql` | PostgreSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `redshift` | Amazon Redshift | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hive` | Apache Hive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cloudscape` | Cloudscape | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hsqldb` | HyperSQL DataBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `progress` | Progress Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `maxdb` | SAP MaxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hanadb` | SAP HANA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ingres` | Ingres | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `firstsql` | FirstSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `edb` | EnterpriseDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `adabas` | Adabas (Adaptable Database System) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `firebird` | Firebird | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `derby` | Apache Derby | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `filemaker` | FileMaker | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `informix` | Informix | ![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) | +| `netezza` | Netezza | ![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) | +| `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) | +| `vertica` | Vertica | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `h2` | H2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `coldfusion` | ColdFusion IMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cassandra` | Apache Cassandra | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hbase` | Apache HBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `redis` | Redis | ![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) | +| `cosmosdb` | Microsoft Azure Cosmos DB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dynamodb` | Amazon DynamoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `geode` | Apache Geode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `elasticsearch` | Elasticsearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cockroachdb` | CockroachDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `opensearch` | OpenSearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `clickhouse` | ClickHouse | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `spanner` | Cloud Spanner | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `trino` | Trino | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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) | + + +## Connection pools + +The following metric instruments describe database client connection pool operations. + +### Metric: `db.client.connection.count` + +This metric is [required][MetricRequired]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.client.connection.count` | UpDownCounter | `{connection}` | The number of connections that are currently in state described by the `state` attribute | ![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 | +|---|---|---|---|---|---| +| [`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.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) | + +### Metric: `db.client.connection.idle.max` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.client.connection.idle.max` | UpDownCounter | `{connection}` | The maximum number of idle open connections allowed | ![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 | +|---|---|---|---|---|---| +| [`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) | + + +### Metric: `db.client.connection.idle.min` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.client.connection.idle.min` | UpDownCounter | `{connection}` | The minimum number of idle open connections allowed | ![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 | +|---|---|---|---|---|---| +| [`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) | + + +### Metric: `db.client.connection.max` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.client.connection.max` | UpDownCounter | `{connection}` | The maximum number of open connections allowed | ![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 | +|---|---|---|---|---|---| +| [`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) | + + +### Metric: `db.client.connection.pending_requests` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.client.connection.pending_requests` | UpDownCounter | `{request}` | The number of pending requests for an open connection, cumulative for the entire pool | ![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 | +|---|---|---|---|---|---| +| [`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) | + + +### Metric: `db.client.connection.timeouts` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.client.connection.timeouts` | Counter | `{timeout}` | The number of connection timeouts that have occurred trying to obtain a connection from the pool | ![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 | +|---|---|---|---|---|---| +| [`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) | + + +### Metric: `db.client.connection.create_time` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.client.connection.create_time` | Histogram | `s` | The time it took to create a new connection | ![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 | +|---|---|---|---|---|---| +| [`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) | + + +### Metric: `db.client.connection.wait_time` -| Name | Instrument | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | -|-------------------------------|----------------------------|-------------|-------------------------------------------|-------------------------------------------------------------------------------------------| -| `db.client.connections.usage` | UpDownCounter | connections | `{connection}` | The number of connections that are currently in state described by the `state` attribute. | +This metric is [recommended][MetricRecommended]. -All `db.client.connections.usage` measurements MUST include the following attribute: + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.client.connection.wait_time` | Histogram | `s` | The time it took to obtain an open connection from the pool | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + -| Name | Type | Description | Examples | Requirement Level | -|---------|--------|------------------------------------------------------------------------------|----------|-------------------| -| `state` | string | The state of a connection in the pool. Valid values include: `idle`, `used`. | `idle` | Required | + +| 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) | + -Instrumentation libraries for database client connection pools that collect data for the following data MUST use the -following metric instruments. Otherwise, if the instrumentation library does not collect this data, these instruments -MUST NOT be used. +### Metric: `db.client.connection.use_time` -| Name | Instrument ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | -|------------------------------------------|----------------------------------------------|--------------|-------------------------------------------|---------------------------------------------------------------------------------------------------| -| `db.client.connections.idle.max` | UpDownCounter | connections | `{connection}` | The maximum number of idle open connections allowed. | -| `db.client.connections.idle.min` | UpDownCounter | connections | `{connection}` | The minimum number of idle open connections allowed. | -| `db.client.connections.max` | UpDownCounter | connections | `{connection}` | The maximum number of open connections allowed. | -| `db.client.connections.pending_requests` | UpDownCounter | requests | `{request}` | The number of pending requests for an open connection, cumulative for the entire pool. | -| `db.client.connections.timeouts` | Counter | timeouts | `{timeout}` | The number of connection timeouts that have occurred trying to obtain a connection from the pool. | -| `db.client.connections.create_time` | Histogram | milliseconds | `ms` | The time it took to create a new connection. | -| `db.client.connections.wait_time` | Histogram | milliseconds | `ms` | The time it took to obtain an open connection from the pool. | -| `db.client.connections.use_time` | Histogram | milliseconds | `ms` | The time between borrowing a connection and returning it to the pool. | +This metric is [recommended][MetricRecommended]. -Below is a table of the attributes that MUST be included on all connection pool measurements: + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.client.connection.use_time` | Histogram | `s` | The time between borrowing a connection and returning it to the pool | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + -| Name | Type | Description | Examples | Requirement Level | -|-------------|--------|------------------------------------------------------------------------------|----------------|-------------------| -| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used. | `myDataSource` | Required | + +| 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) | + -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md +[MetricRequired]: /docs/general/metric-requirement-level.md#required +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 9c60f6001e..919a736301 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -10,131 +10,180 @@ linkTitle: Client Calls -- [Connection-level attributes](#connection-level-attributes) - * [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem) -- [Call-level attributes](#call-level-attributes) +- [Name](#name) +- [Common attributes](#common-attributes) + - [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem) - [Semantic Conventions for specific database technologies](#semantic-conventions-for-specific-database-technologies) +> **Warning** +> Existing database instrumentations that are using +> [v1.24.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md) +> (or prior) SHOULD NOT change the version of the database conventions that they emit +> 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. +> > **Warning** > Existing Database instrumentations that are using > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/database.md) > (or prior): > -> * SHOULD NOT change the version of the networking attributes that they emit +> * SHOULD NOT change the version of the networking conventions that they emit > until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in Database instrumentations). +> include stabilization of a core set of networking conventions which are also used +> in Database instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable networking attributes, -> and stop emitting the old experimental networking attributes +> * `http` - emit the new, stable networking conventions, +> and stop emitting the old experimental networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable networking attributes, +> * `http/dup` - emit both the old and the stable networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental networking attributes +> emitting whatever version of the old experimental networking conventions > the instrumentation was emitting previously. +> * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). +> for at least six months after it starts emitting both sets of conventions. +> * SHOULD drop the environment variable in the next major version. **Span kind:** MUST always be `CLIENT`. -The **span name** SHOULD be set to a low cardinality value representing the statement executed on the database. -It MAY be a stored procedure name (without arguments), DB statement without variable arguments, operation name, etc. -Since SQL statements may have very high cardinality even without arguments, SQL spans SHOULD be named the -following way, unless the statement is known to be of low cardinality: -` .`, provided that `db.operation` and `db.sql.table` are available. -If `db.sql.table` is not available due to its semantics, the span SHOULD be named ` `. -It is not recommended to attempt any client-side parsing of `db.statement` just to get these properties, -they should only be used if the library being instrumented already provides them. -When it's otherwise impossible to get any meaningful span name, `db.name` or the tech-specific database name MAY be used. +Span that describes database call SHOULD cover the duration of the corresponding call as if it was observed by the caller (such as client application). +For example, if a transient issue happened and was retried within this database call, the corresponding span should cover the duration of the logical operation +with all retries. + +## Name + +Database spans MUST 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 `{db.operation.name} {target}` if there is a +(low-cardinality) `db.operation.name` available (see below for the exact definition of the [`{target}`](#target-placeholder) placeholder). + +If there is no (low-cardinality) `db.operation.name` available, database span names +SHOULD be [`{target}`](#target-placeholder). + + +Semantic conventions for individual database systems MAY specify different span name format. + +The `{target}` SHOULD adhere to one of the following values, arranged in prioritized order, provided they are accessible: + +- `db.collection.name` +- `db.namespace` +- `server.address:server.port` +- `db.system` -## Connection-level attributes +## Common attributes These attributes will usually be the same for all operations performed over the same database connection. -Some database systems may allow a connection to switch to a different `db.user`, for example, and other database systems may not even have the concept of a connection at all. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required | -| `db.connection_string` | string | The connection string used to connect to the database. It is recommended to remove embedded credentials. | `Server=(localdb)\v11.0;Integrated Security=true;` | Recommended | -| `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended | -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the database host. | `example.com` | Conditionally Required: See alternative attributes below. | -| [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: [1] | -| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | See below | -| [`server.socket.port`](../general/attributes.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | - -**[1]:** If using a port other than the default port for this DBMS and if `server.address` is set. - -**Additional attribute requirements:** At least one of the following sets of attributes is required: - -* [`server.address`](../general/attributes.md) -* [`server.socket.address`](../general/attributes.md) - -`db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. - -| Value | Description | -|---|---| -| `other_sql` | Some other SQL database. Fallback only. See notes. | -| `mssql` | Microsoft SQL Server | -| `mssqlcompact` | Microsoft SQL Server Compact | -| `mysql` | MySQL | -| `oracle` | Oracle Database | -| `db2` | IBM Db2 | -| `postgresql` | PostgreSQL | -| `redshift` | Amazon Redshift | -| `hive` | Apache Hive | -| `cloudscape` | Cloudscape | -| `hsqldb` | HyperSQL DataBase | -| `progress` | Progress Database | -| `maxdb` | SAP MaxDB | -| `hanadb` | SAP HANA | -| `ingres` | Ingres | -| `firstsql` | FirstSQL | -| `edb` | EnterpriseDB | -| `cache` | InterSystems Caché | -| `adabas` | Adabas (Adaptable Database System) | -| `firebird` | Firebird | -| `derby` | Apache Derby | -| `filemaker` | FileMaker | -| `informix` | Informix | -| `instantdb` | InstantDB | -| `interbase` | InterBase | -| `mariadb` | MariaDB | -| `netezza` | Netezza | -| `pervasive` | Pervasive PSQL | -| `pointbase` | PointBase | -| `sqlite` | SQLite | -| `sybase` | Sybase | -| `teradata` | Teradata | -| `vertica` | Vertica | -| `h2` | H2 | -| `coldfusion` | ColdFusion IMQ | -| `cassandra` | Apache Cassandra | -| `hbase` | Apache HBase | -| `mongodb` | MongoDB | -| `redis` | Redis | -| `couchbase` | Couchbase | -| `couchdb` | CouchDB | -| `cosmosdb` | Microsoft Azure Cosmos DB | -| `dynamodb` | Amazon DynamoDB | -| `neo4j` | Neo4j | -| `geode` | Apache Geode | -| `elasticsearch` | Elasticsearch | -| `memcached` | Memcached | -| `cockroachdb` | CockroachDB | -| `opensearch` | OpenSearch | -| `clickhouse` | ClickHouse | -| `spanner` | Cloud Spanner | -| `trino` | Trino | + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`db.system`](/docs/attributes-registry/db.md) | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql`; `mssql`; `mssqlcompact` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [3] | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [4] | ![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.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` 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. [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) | + +**[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. + +**[2]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.collection.name`, then it SHOULD be the first collection name found in the query. + +**[3]:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid. +Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. + +**[4]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. + +**[5]:** The `error.type` SHOULD match the error code returned by the database 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. + +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[7]:** If using a port other than the default port for this DBMS and if `server.address` is set. + +**[8]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. + +**[9]:** 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. + +**[10]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + +**[11]:** 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. + +`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 | +|---|---|---| +| `other_sql` | Some other SQL database. Fallback only. See notes. | ![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) | +| `oracle` | Oracle Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db2` | IBM Db2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `postgresql` | PostgreSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `redshift` | Amazon Redshift | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hive` | Apache Hive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cloudscape` | Cloudscape | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hsqldb` | HyperSQL DataBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `progress` | Progress Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `maxdb` | SAP MaxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hanadb` | SAP HANA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ingres` | Ingres | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `firstsql` | FirstSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `edb` | EnterpriseDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `adabas` | Adabas (Adaptable Database System) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `firebird` | Firebird | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `derby` | Apache Derby | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `filemaker` | FileMaker | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `informix` | Informix | ![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) | +| `netezza` | Netezza | ![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) | +| `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) | +| `vertica` | Vertica | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `h2` | H2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `coldfusion` | ColdFusion IMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cassandra` | Apache Cassandra | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hbase` | Apache HBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `redis` | Redis | ![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) | +| `cosmosdb` | Microsoft Azure Cosmos DB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dynamodb` | Amazon DynamoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `geode` | Apache Geode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `elasticsearch` | Elasticsearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cockroachdb` | CockroachDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `opensearch` | OpenSearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `clickhouse` | ClickHouse | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `spanner` | Cloud Spanner | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `trino` | Trino | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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) | ### Notes and well-known identifiers for `db.system` @@ -151,29 +200,10 @@ This allows multiple instrumentations for the same database to be aligned and ea The value `other_sql` is intended as a fallback and MUST only be used if the DBMS is known to be SQL-compliant but the concrete product is not known to the instrumentation. If the concrete DBMS is known to the instrumentation, its specific identifier MUST be used. -Back ends could, for example, use the provided identifier to determine the appropriate SQL dialect for parsing the `db.statement`. +Back ends could, for example, use the provided identifier to determine the appropriate SQL dialect for parsing the `db.query.text`. 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. -## Call-level attributes - -These attributes may be different for each operation performed, even if the same connection is used for multiple operations. -Usually only one `db.name` will be used per connection though. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `db.name` | string | This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | Conditionally Required: If applicable. | -| `db.statement` | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | Recommended: [2] | -| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. [3] | `findAndModify`; `HMSET`; `SELECT` | Conditionally Required: If `db.statement` is not applicable. | - -**[1]:** In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name). - -**[2]:** Should be collected by default only if there is sanitization that excludes sensitive information. - -**[3]:** When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. - - ## Semantic Conventions for specific database technologies More specific Semantic Conventions are defined for the following database technologies: @@ -183,11 +213,10 @@ More specific Semantic Conventions are defined for the following database techno * [Cosmos DB](cosmosdb.md): Semantic Conventions for *Microsoft Cosmos DB*. * [CouchDB](couchdb.md): Semantic Conventions for *CouchDB*. * [Elasticsearch](elasticsearch.md): Semantic Conventions for *Elasticsearch*. -* [GraphQL](graphql.md): Semantic Conventions for *GraphQL Server*. * [HBase](hbase.md): Semantic Conventions for *HBase*. * [MongoDB](mongodb.md): Semantic Conventions for *MongoDB*. * [MSSQL](mssql.md): Semantic Conventions for *MSSQL*. * [Redis](redis.md): Semantic Conventions for *Redis*. * [SQL](sql.md): Semantic Conventions for *SQL* databases. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/database/dynamodb.md b/docs/database/dynamodb.md index f37e918366..099db4d1a7 100644 --- a/docs/database/dynamodb.md +++ b/docs/database/dynamodb.md @@ -17,157 +17,448 @@ described on this page. These attributes are filled in for all DynamoDB request types. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`db.system`](database-spans.md) | string | The value `dynamodb`. | `dynamodb` | Required | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`db.system`](/docs/attributes-registry/db.md) | string | The value `dynamodb`. | `dynamodb` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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 | +|---|---|---| +| `other_sql` | Some other SQL database. Fallback only. See notes. | ![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) | +| `oracle` | Oracle Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db2` | IBM Db2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `postgresql` | PostgreSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `redshift` | Amazon Redshift | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hive` | Apache Hive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cloudscape` | Cloudscape | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hsqldb` | HyperSQL DataBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `progress` | Progress Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `maxdb` | SAP MaxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hanadb` | SAP HANA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ingres` | Ingres | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `firstsql` | FirstSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `edb` | EnterpriseDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `adabas` | Adabas (Adaptable Database System) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `firebird` | Firebird | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `derby` | Apache Derby | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `filemaker` | FileMaker | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `informix` | Informix | ![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) | +| `netezza` | Netezza | ![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) | +| `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) | +| `vertica` | Vertica | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `h2` | H2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `coldfusion` | ColdFusion IMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cassandra` | Apache Cassandra | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hbase` | Apache HBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `redis` | Redis | ![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) | +| `cosmosdb` | Microsoft Azure Cosmos DB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dynamodb` | Amazon DynamoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `geode` | Apache Geode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `elasticsearch` | Elasticsearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cockroachdb` | CockroachDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `opensearch` | OpenSearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `clickhouse` | ClickHouse | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `spanner` | Cloud Spanner | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `trino` | Trino | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## DynamoDB.BatchGetItem -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.table_names` | string[] | The keys in the `RequestItems` object field. | `[Users, Cats]` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | The keys in the `RequestItems` object field. | `Users`; `Cats` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## DynamoDB.BatchWriteItem -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | Recommended | -| `aws.dynamodb.table_names` | string[] | The keys in the `RequestItems` object field. | `[Users, Cats]` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.item_collection_metrics`](/docs/attributes-registry/aws.md) | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | The keys in the `RequestItems` object field. | `Users`; `Cats` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## DynamoDB.CreateTable -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.global_secondary_indexes` | string[] | The JSON-serialized value of each item of the `GlobalSecondaryIndexes` request field | `[{ "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }]` | Recommended | -| `aws.dynamodb.local_secondary_indexes` | string[] | The JSON-serialized value of each item of the `LocalSecondaryIndexes` request field. | `[{ "IndexArn": "string", "IndexName": "string", "IndexSizeBytes": number, "ItemCount": number, "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" } }]` | Recommended | -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | Recommended | -| `aws.dynamodb.provisioned_read_capacity` | double | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. | `1.0`; `2.0` | Recommended | -| `aws.dynamodb.provisioned_write_capacity` | double | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. | `1.0`; `2.0` | Recommended | -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.global_secondary_indexes`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item of the `GlobalSecondaryIndexes` request field | `{ "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.item_collection_metrics`](/docs/attributes-registry/aws.md) | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.local_secondary_indexes`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item of the `LocalSecondaryIndexes` request field. | `{ "IndexArn": "string", "IndexName": "string", "IndexSizeBytes": number, "ItemCount": number, "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" } }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.provisioned_read_capacity`](/docs/attributes-registry/aws.md) | double | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. | `1`; `2` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.provisioned_write_capacity`](/docs/attributes-registry/aws.md) | double | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. | `1`; `2` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `Users` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## DynamoDB.DeleteItem -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | Recommended | -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.item_collection_metrics`](/docs/attributes-registry/aws.md) | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `Users` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## DynamoDB.DeleteTable -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `Users` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## DynamoDB.DescribeTable -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `Users` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## DynamoDB.GetItem -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.consistent_read` | boolean | The value of the `ConsistentRead` request parameter. | | Recommended | -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.projection` | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | Recommended | -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.consistent_read`](/docs/attributes-registry/aws.md) | boolean | The value of the `ConsistentRead` request parameter. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.projection`](/docs/attributes-registry/aws.md) | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `Users` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## DynamoDB.ListTables -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.exclusive_start_table` | string | The value of the `ExclusiveStartTableName` request parameter. | `Users`; `CatsTable` | Recommended | -| `aws.dynamodb.table_count` | int | The the number of items in the `TableNames` response parameter. | `20` | Recommended | -| `aws.dynamodb.limit` | int | The value of the `Limit` request parameter. | `10` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.exclusive_start_table`](/docs/attributes-registry/aws.md) | string | The value of the `ExclusiveStartTableName` request parameter. | `Users`; `CatsTable` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.limit`](/docs/attributes-registry/aws.md) | int | The value of the `Limit` request parameter. | `10` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.table_count`](/docs/attributes-registry/aws.md) | int | The number of items in the `TableNames` response parameter. | `20` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## DynamoDB.PutItem -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | Recommended | -| `aws.dynamodb.table_names` | string[] | The keys in the `RequestItems` object field. | `[Users, Cats]` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.item_collection_metrics`](/docs/attributes-registry/aws.md) | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | The keys in the `RequestItems` object field. | `Users`; `Cats` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## DynamoDB.Query -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.scan_forward` | boolean | The value of the `ScanIndexForward` request parameter. | | Recommended | -| `aws.dynamodb.attributes_to_get` | string[] | The value of the `AttributesToGet` request parameter. | `[lives, id]` | Recommended | -| `aws.dynamodb.consistent_read` | boolean | The value of the `ConsistentRead` request parameter. | | Recommended | -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.index_name` | string | The value of the `IndexName` request parameter. | `name_to_group` | Recommended | -| `aws.dynamodb.limit` | int | The value of the `Limit` request parameter. | `10` | Recommended | -| `aws.dynamodb.projection` | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | Recommended | -| `aws.dynamodb.select` | string | The value of the `Select` request parameter. | `ALL_ATTRIBUTES`; `COUNT` | Recommended | -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.attributes_to_get`](/docs/attributes-registry/aws.md) | string[] | The value of the `AttributesToGet` request parameter. | `lives`; `id` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.consistent_read`](/docs/attributes-registry/aws.md) | boolean | The value of the `ConsistentRead` request parameter. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.index_name`](/docs/attributes-registry/aws.md) | string | The value of the `IndexName` request parameter. | `name_to_group` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.limit`](/docs/attributes-registry/aws.md) | int | The value of the `Limit` request parameter. | `10` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.projection`](/docs/attributes-registry/aws.md) | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.scan_forward`](/docs/attributes-registry/aws.md) | boolean | The value of the `ScanIndexForward` request parameter. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.select`](/docs/attributes-registry/aws.md) | string | The value of the `Select` request parameter. | `ALL_ATTRIBUTES`; `COUNT` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `Users` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## DynamoDB.Scan -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.segment` | int | The value of the `Segment` request parameter. | `10` | Recommended | -| `aws.dynamodb.total_segments` | int | The value of the `TotalSegments` request parameter. | `100` | Recommended | -| `aws.dynamodb.count` | int | The value of the `Count` response parameter. | `10` | Recommended | -| `aws.dynamodb.scanned_count` | int | The value of the `ScannedCount` response parameter. | `50` | Recommended | -| `aws.dynamodb.attributes_to_get` | string[] | The value of the `AttributesToGet` request parameter. | `[lives, id]` | Recommended | -| `aws.dynamodb.consistent_read` | boolean | The value of the `ConsistentRead` request parameter. | | Recommended | -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.index_name` | string | The value of the `IndexName` request parameter. | `name_to_group` | Recommended | -| `aws.dynamodb.limit` | int | The value of the `Limit` request parameter. | `10` | Recommended | -| `aws.dynamodb.projection` | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | Recommended | -| `aws.dynamodb.select` | string | The value of the `Select` request parameter. | `ALL_ATTRIBUTES`; `COUNT` | Recommended | -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.attributes_to_get`](/docs/attributes-registry/aws.md) | string[] | The value of the `AttributesToGet` request parameter. | `lives`; `id` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.consistent_read`](/docs/attributes-registry/aws.md) | boolean | The value of the `ConsistentRead` request parameter. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.count`](/docs/attributes-registry/aws.md) | int | The value of the `Count` response parameter. | `10` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.index_name`](/docs/attributes-registry/aws.md) | string | The value of the `IndexName` request parameter. | `name_to_group` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.limit`](/docs/attributes-registry/aws.md) | int | The value of the `Limit` request parameter. | `10` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.projection`](/docs/attributes-registry/aws.md) | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.scanned_count`](/docs/attributes-registry/aws.md) | int | The value of the `ScannedCount` response parameter. | `50` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.segment`](/docs/attributes-registry/aws.md) | int | The value of the `Segment` request parameter. | `10` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.select`](/docs/attributes-registry/aws.md) | string | The value of the `Select` request parameter. | `ALL_ATTRIBUTES`; `COUNT` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `Users` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.total_segments`](/docs/attributes-registry/aws.md) | int | The value of the `TotalSegments` request parameter. | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## DynamoDB.UpdateItem -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | Recommended | -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.item_collection_metrics`](/docs/attributes-registry/aws.md) | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `Users` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## DynamoDB.UpdateTable -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.attribute_definitions` | string[] | The JSON-serialized value of each item in the `AttributeDefinitions` request field. | `[{ "AttributeName": "string", "AttributeType": "string" }]` | Recommended | -| `aws.dynamodb.global_secondary_index_updates` | string[] | The JSON-serialized value of each item in the the `GlobalSecondaryIndexUpdates` request field. | `[{ "Create": { "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }]` | Recommended | -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.provisioned_read_capacity` | double | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. | `1.0`; `2.0` | Recommended | -| `aws.dynamodb.provisioned_write_capacity` | double | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. | `1.0`; `2.0` | Recommended | -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.attribute_definitions`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `AttributeDefinitions` request field. | `{ "AttributeName": "string", "AttributeType": "string" }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.global_secondary_index_updates`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `GlobalSecondaryIndexUpdates` request field. | `{ "Create": { "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.provisioned_read_capacity`](/docs/attributes-registry/aws.md) | double | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. | `1`; `2` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.provisioned_write_capacity`](/docs/attributes-registry/aws.md) | double | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. | `1`; `2` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `Users` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index bf1aa46360..cb4aa286ff 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -6,7 +6,11 @@ linkTitle: Elasticsearch **Status**: [Experimental][DocumentStatus] -This document defines semantic conventions to apply when creating a span for requests to Elasticsearch. +The Semantic Conventions for [Elasticsearch](https://www.elastic.co/) extend and override the [Database Semantic Conventions](database-spans.md) +that describe common database operations attributes in addition to the Semantic Conventions +described on this page. + +`db.system` MUST be set to `"elasticsearch"`. ## Span Name @@ -17,43 +21,30 @@ name, as the path could contain dynamic values. The endpoint id is the `name` fi [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`. -## URL path parts - -Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format -`db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD -reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) -in order to map the path part values to their names. - -| Attribute | Type | Description | Examples | Requirement Level | -|-------------------------------------|---|---------------------------------------|------------------------------------------------------------------------------------------|---| -| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | Conditionally Required: [1] | - -**[1]:** when the url has dynamic values - -## Span attributes - -`db.system` MUST be set to `"elasticsearch"`. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`db.operation`](database-spans.md) | string | The endpoint identifier for the request. [1] | `search`; `ml.close_job`; `cat.aliases` | Required | -| [`db.statement`](database-spans.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. | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | Recommended: [2] | -| `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required | -| [`server.address`](../general/attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | See below | -| [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Recommended | -| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [4] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required | - -**[1]:** When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. - -**[2]:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information. - -**[3]:** HTTP request method value SHOULD be "known" to the instrumentation. +## Attributes + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `search`; `ml.close_job`; `cat.aliases` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.full`](/docs/attributes-registry/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [3] | `https://localhost:9200/index/_search?q=user.id:kimchy` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [5] | `80`; `8080`; `443` | `Conditionally Required` [6] | ![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` [7] | ![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` [8] | ![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. | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | `Recommended` [9] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [10] | `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. [11] | `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. + +**[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) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER` and, except if reporting a metric, MUST -set the exact method received in the request line as value of the `http.request.method_original` attribute. +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named @@ -64,9 +55,40 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[4]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. -`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`. -`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes. +**[3]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. +`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. + +**[4]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names. + +**[5]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[6]:** If using a port other than the default port for this DBMS and if `server.address` is set. + +**[7]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. + +**[8]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header. + +**[9]:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information. + +**[10]:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. + +**[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. + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `CONNECT` | CONNECT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `DELETE` | DELETE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `GET` | GET method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `HEAD` | HEAD method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `OPTIONS` | OPTIONS method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PATCH` | PATCH method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `POST` | POST method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ## Example @@ -78,9 +100,11 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original | `server.address` | `"elasticsearch.mydomain.com"` | | `server.port` | `9200` | | `http.request.method` | `"GET"` | -| `db.statement` | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | -| `db.operation` | `"search"` | +| `db.query.text` | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | +| `db.operation.name` | `"search"` | | `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"` | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/database/graphql.md b/docs/database/graphql.md deleted file mode 100644 index 8cc6409866..0000000000 --- a/docs/database/graphql.md +++ /dev/null @@ -1,35 +0,0 @@ - - -# Semantic Conventions for GraphQL Server - -**Status**: [Experimental][DocumentStatus] - -This document defines semantic conventions to apply when instrumenting the GraphQL implementation. They map GraphQL -operations to attributes on a Span. - -The **span name** MUST be of the format ` ` provided that -`graphql.operation.type` and `graphql.operation.name` are available. If `graphql.operation.name` is not available, the -span SHOULD be named ``. When `` is not available, `GraphQL Operation` -MAY be used as span name. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `graphql.operation.name` | string | The name of the operation being executed. | `findBookById` | Recommended | -| `graphql.operation.type` | string | The type of the operation being executed. | `query`; `mutation`; `subscription` | Recommended | -| `graphql.document` | string | The GraphQL document being executed. [1] | `query findBookById { bookById(id: ?) { name } }` | Recommended | - -**[1]:** The value may be sanitized to exclude sensitive information. - -`graphql.operation.type` MUST be one of the following: - -| Value | Description | -|---|---| -| `query` | GraphQL query | -| `mutation` | GraphQL mutation | -| `subscription` | GraphQL subscription | - - -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/database/hbase.md b/docs/database/hbase.md index 2c51ce763e..40fd9be549 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -12,14 +12,17 @@ described on this page. `db.system` MUST be set to `"hbase"`. -## Call-level attributes +## Attributes - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`db.name`](database-spans.md) | string | The HBase namespace. [1] | `mynamespace` | Conditionally Required: If applicable. | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The HBase table name. [1] | `mytable`; `ns:table` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The HBase namespace. [2] | `mynamespace` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** For HBase the `db.name` should be set to the HBase namespace. +**[1]:** If table name includes the namespace, the `db.collection.name` SHOULD be set to the full table name. + +**[2]:** When performing table-related operations, the instrumentations SHOULD extract the namespace from the table name according to the [HBase table naming conventions](https://hbase.apache.org/book.html#namespace_creation). If namespace is not provided, instrumentation SHOULD set `db.namespace` value to `default`. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index d3d3608272..7a48550c8f 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -12,29 +12,38 @@ described on this page. `db.system` MUST be set to `"mongodb"`. -## Call-level attributes +## Attributes - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `db.mongodb.collection` | string | The collection being accessed within the database stated in `db.name`. | `customers`; `products` | Required | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The MongoDB collection being accessed within the database stated in `db.namespace`. [1] | `public.users`; `customers` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The MongoDB database name. [2] | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the command being executed. [3] | `findAndModify`; `getMore`; `update` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. + +**[2]:** + +**[3]:** See [MongoDB database commands](https://www.mongodb.com/docs/manual/reference/command/). + +**[4]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. ## Example -| Key | Value | -| :---------------------- | :----------------------------------------------------------- | -| Span name | `"products.findAndModify"` | +| Key | Value | +|:------------------------| :----------------------------------------------------------- | +| Span name | `"findAndModify products"` | | `db.system` | `"mongodb"` | -| `db.connection_string` | not set | -| `db.user` | `"the_user"` | | `server.address` | `"mongodb0.example.com"` | -| `server.socket.address` | `"192.0.2.14"` | | `server.port` | `27017` | -| `network.transport` | `"IP.TCP"` | -| `db.name` | `"shopDb"` | -| `db.statement` | not set | -| `db.operation` | `"findAndModify"` | -| `db.mongodb.collection` | `"products"` | - -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +| `network.peer.address` | `"192.0.2.14"` | +| `network.peer.port` | `27017` | +| `network.transport` | `"tcp"` | +| `db.collection.name` | `"products"` | +| `db.namespace` | `"shopDb"` | +| `db.query.text` | not set | +| `db.operation.name` | `"findAndModify"` | + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/database/mssql.md b/docs/database/mssql.md index ee1bc5e099..c27cc54f2d 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -6,21 +6,32 @@ linkTitle: MSSQL **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for the [Microsoft SQL Server](https://www.microsoft.com/sql-server) extend and override the [Database Semantic Conventions](database-spans.md) +The Semantic Conventions for the *Microsoft SQL Server* extend and override the [Database Semantic Conventions](database-spans.md) that describe common database operations attributes in addition to the Semantic Conventions described on this page. `db.system` MUST be set to `"mssql"`. -## Connection-level attributes +## Attributes - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`db.jdbc.driver_classname`](database-spans.md) | string | The fully-qualified class name of the [Java Database Connectivity (JDBC)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) driver used to connect. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | Recommended | -| `db.mssql.instance_name` | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [1] | `MSSQLSERVER` | Recommended | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of the SQL table that the operation is acting upon. [1] | `users`; `dbo.products` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [3] | `instance1.products`; `customers` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `SELECT`; `INSERT`; `UPDATE`; `DELETE`; `CREATE`; `mystoredproc` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** If setting a `db.mssql.instance_name`, `server.port` is no longer required (but still recommended if non-standard). +**[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. + +**[2]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.collection.name`, then it SHOULD be the first collection name found in the query. + +**[3]:** When connecting to a default instance, `db.namespace` SHOULD be set to the name of the database. When connecting to a [named instance](https://learn.microsoft.com/sql/connect/jdbc/building-the-connection-url#named-and-multiple-sql-server-instances), `db.namespace` SHOULD be set to the combination of instance and database name following the `{instance_name}.{database_name}` pattern. +For commands that switch the database, this SHOULD be set to the target database (even if the command fails). + +**[4]:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`. +In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed. + +**[5]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/database/redis.md b/docs/database/redis.md index f7e8d41079..25706de783 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -12,35 +12,39 @@ described on this page. `db.system` MUST be set to `"redis"`. -## Call-level attributes +## Attributes - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `db.redis.database_index` | int | The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. | `0`; `1`; `15` | Conditionally Required: If other than the default database (`0`). | -| [`db.statement`](database-spans.md) | string | The full syntax of the Redis CLI command. [1] | `HMSET myhash field1 'Hello' field2 'World'` | Recommended: [2] | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select). [1] | `0`; `1`; `15` | `Conditionally Required` If and only if it can be captured reliably. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The full syntax of the Redis CLI command. [2] | `HMSET myhash field1 'Hello' field2 'World'` | `Recommended` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [4] | `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) | -**[1]:** For **Redis**, the value provided for `db.statement` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.statement`. +**[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. +For commands that switch the database, this SHOULD be set to the target database (even if the command fails). -**[2]:** Should be collected by default only if there is sanitization that excludes sensitive information. +**[2]:** For **Redis**, the value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`. + +**[3]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. + +**[4]:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. ## Example -In this example, Redis is connected using a unix domain socket and therefore the connection string and `server.address` are left out. -Furthermore, `db.name` is not specified as there is no database name in Redis and `db.redis.database_index` is set instead. +In this example, Redis is connected using a unix domain socket and therefore the connection string is left out. | Key | Value | |:--------------------------| :-------------------------------------------- | -| Span name | `"HMSET myhash"` | +| Span name | `"HMSET 15"` | | `db.system` | `"redis"` | -| `db.connection_string` | not set | -| `db.user` | not set | -| `server.socket.address` | `"/tmp/redis.sock"` | -| `network.transport` | `"Unix"` | -| `db.name` | not set | -| `db.statement` | `"HMSET myhash field1 'Hello' field2 'World"` | -| `db.operation` | not set | -| `db.redis.database_index` | `15` | - -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +| `network.peer.address` | `"/tmp/redis.sock"` | +| `network.transport` | `"unix"` | +| `db.namespace` | `"15"` | +| `db.query.text` | `"HMSET myhash field1 'Hello' field2 'World"` | +| `db.operation.name` | `"HMSET"` | + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/database/sql.md b/docs/database/sql.md index 7fe9370f79..84c1021c37 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -10,33 +10,61 @@ The SQL databases Semantic Conventions extend and override the [Database Semanti that describe common database operations attributes in addition to the Semantic Conventions described on this page. -## Call-level attributes +## Attributes - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `db.sql.table` | string | The name of the primary table that the operation is acting upon, including the database name (if applicable). [1] | `public.users`; `customers` | Recommended | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of the SQL table that the operation is acting upon. [1] | `users`; `dbo.products` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [3] | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `SELECT`; `INSERT`; `UPDATE`; `DELETE`; `CREATE`; `mystoredproc` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set. +**[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. + +**[2]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.collection.name`, then it SHOULD be the first collection name found in the query. + +**[3]:** If a database system has multiple namespace components, they SHOULD be concatenated +(potentially using database system specific conventions) from most general to most +specific namespace component, and more specific namespaces SHOULD NOT be captured without +the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid. + +Unless specified by the system-specific semantic convention, the `db.namespace` attribute matches +the name of the database being accessed. + +The database name can usually be obtained with database driver API such as +[JDBC `Connection.getCatalog()`](https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html#getCatalog--) +or [.NET `SqlConnection.Database`](https://learn.microsoft.com/dotnet/api/system.data.sqlclient.sqlconnection.database). + +Some database drivers don't detect when the current database is changed (for example, with SQL `USE database` statement). +Instrumentations that parse SQL statements MAY use the database name provided +in the connection string and keep track of the currently selected database name. + +For commands that switch the database, this SHOULD be set to the target database (even if the command fails). + +If instrumentation cannot reliably determine the current database name, it SHOULD NOT set `db.namespace`. + +**[4]:** This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`. +In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed. + +**[5]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. ## Example This is an example of attributes for a MySQL database span: -| Key | Value | -|:------------------------| :----------------------------------------------------------- | -| Span name | `"SELECT ShopDb.orders"` | -| `db.system` | `"mysql"` | -| `db.connection_string` | `"Server=shopdb.example.com;Database=ShopDb;Uid=billing_user;TableCache=true;UseCompression=True;MinimumPoolSize=10;MaximumPoolSize=50;"` | -| `db.user` | `"billing_user"` | -| `server.address` | `"shopdb.example.com"` | -| `server.socket.address` | `"192.0.2.12"` | -| `server.port` | `3306` | -| `network.transport` | `"IP.TCP"` | -| `db.name` | `"ShopDb"` | -| `db.statement` | `"SELECT * FROM orders WHERE order_id = 'o4711'"` | -| `db.operation` | `"SELECT"` | -| `db.sql.table` | `"orders"` | - -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +| Key | Value | +|:-----------------------| :----------------------------------------------------------- | +| Span name | `"SELECT ShopDb.orders"` | +| `db.collection.name` | `"orders"` | +| `db.namespace` | `"ShopDb"` | +| `db.system` | `"mysql"` | +| `server.address` | `"shopdb.example.com"` | +| `server.port` | `3306` | +| `network.peer.address` | `"192.0.2.12"` | +| `network.peer.port` | `3306` | +| `network.transport` | `"tcp"` | +| `db.query.text` | `"SELECT * FROM orders WHERE order_id = 'o4711'"` | +| `db.operation.name` | `"SELECT"` | + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/dns/dns-metrics.md b/docs/dns/dns-metrics.md new file mode 100644 index 0000000000..e940ab4a9b --- /dev/null +++ b/docs/dns/dns-metrics.md @@ -0,0 +1,53 @@ + + +# Semantic Conventions for DNS queries + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions to apply when instrumenting DNS queries. + + + + + +- [Metrics](#metrics) + - [Metric: `dns.lookup.duration`](#metric-dnslookupduration) + + + +## Metrics + +### Metric: `dns.lookup.duration` + +This metric is optional. + +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.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 | +| -------- | --------------- | ----------- | -------------- | --------- | +| `dns.lookup.duration` | Histogram | `s` | Measures the time taken to perform a DNS lookup. | ![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 | +|---|---|---|---|---|---| +| [`dns.question.name`](/docs/attributes-registry/dns.md) | string | The name being queried. [1] | `www.example.com`; `dot.net` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes the error the DNS lookup failed with. [2] | `host_not_found`; `no_recovery`; `java.net.UnknownHostException` | `Conditionally Required` if and only if an error has occurred. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** If the name field contains non-printable characters (below 32 or above 126), those characters should be represented as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. Tabs, carriage returns, and line feeds should be converted to \t, \r, and \n respectively. + +**[2]:** Instrumentations SHOULD use error code such as one of errors reported by `getaddrinfo`([Linux or other POSIX systems](https://man7.org/linux/man-pages/man3/getaddrinfo.3.html) / [Windows](https://learn.microsoft.com/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo)) or one reported by the runtime or client library. If error code is not available, the full name of exception type SHOULD be used. + +`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) | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/dotnet/README.md b/docs/dotnet/README.md new file mode 100644 index 0000000000..e2c09609d8 --- /dev/null +++ b/docs/dotnet/README.md @@ -0,0 +1,22 @@ + + +# Semantic Conventions for .NET metrics + +**Status**: [Stable][DocumentStatus] + +This article documents semantic conventions for metrics emitted by the .NET runtime and individual components in the .NET ecosystem. + +The following metrics are currently supported: + +* [ASP.NET Core](dotnet-aspnetcore-metrics.md): Semantic Conventions for ASP.NET Core routing, exceptions, and rate-limiting *metrics*. +* [DNS](dotnet-dns-metrics.md): Semantic Conventions for client-side DNS lookups associated with *metrics*. +* [HTTP](dotnet-http-metrics.md): Semantic Conventions for HTTP client and server *metrics*. +* [Kestrel](dotnet-kestrel-metrics.md): Semantic Conventions for Kestrel web server *metrics*. +* [SignalR](dotnet-signalr-metrics.md): Semantic Conventions for SignalR server *metrics*. + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md new file mode 100644 index 0000000000..3ff1cebb4b --- /dev/null +++ b/docs/dotnet/dotnet-aspnetcore-metrics.md @@ -0,0 +1,247 @@ + + +# Semantic Conventions for ASP.NET Core metrics + +**Status**: [Stable][DocumentStatus] + +This article defines semantic conventions for ASP.NET Core metrics. + + + +- [Server](#server) +- [Routing](#routing) + - [Metric: `aspnetcore.routing.match_attempts`](#metric-aspnetcoreroutingmatch_attempts) +- [Exceptions](#exceptions) + - [Metric: `aspnetcore.diagnostics.exceptions`](#metric-aspnetcorediagnosticsexceptions) +- [Rate-limiting](#rate-limiting) + - [Metric: `aspnetcore.rate_limiting.active_request_leases`](#metric-aspnetcorerate_limitingactive_request_leases) + - [Metric: `aspnetcore.rate_limiting.request_lease.duration`](#metric-aspnetcorerate_limitingrequest_leaseduration) + - [Metric: `aspnetcore.rate_limiting.queued_requests`](#metric-aspnetcorerate_limitingqueued_requests) + - [Metric: `aspnetcore.rate_limiting.request.time_in_queue`](#metric-aspnetcorerate_limitingrequesttime_in_queue) + - [Metric: `aspnetcore.rate_limiting.requests`](#metric-aspnetcorerate_limitingrequests) + + + +## Server + +## Routing + +All routing metrics are reported by the `Microsoft.AspNetCore.Routing` meter. + +### Metric: `aspnetcore.routing.match_attempts` + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `aspnetcore.routing.match_attempts` | Counter | `{match_attempt}` | Number of requests that were attempted to be matched to an endpoint. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Meter name: `Microsoft.AspNetCore.Routing`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`aspnetcore.routing.match_status`](/docs/attributes-registry/aspnetcore.md) | string | Match result - success or failure | `success`; `failure` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`aspnetcore.routing.is_fallback`](/docs/attributes-registry/aspnetcore.md) | boolean | A value that indicates whether the matched route is a fallback route. | `true` | `Conditionally Required` if and only if a route was successfully matched. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.route`](/docs/attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` if and only if a route was successfully matched. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. + +`aspnetcore.routing.match_status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `success` | Match succeeded | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `failure` | Match failed | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +## Exceptions + +Exceptions Metric is reported by the `Microsoft.AspNetCore.Diagnostics` meter. + +### Metric: `aspnetcore.diagnostics.exceptions` + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `aspnetcore.diagnostics.exceptions` | Counter | `{exception}` | Number of exceptions caught by exception handling middleware. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Meter name: `Microsoft.AspNetCore.Diagnostics`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`aspnetcore.diagnostics.exception.result`](/docs/attributes-registry/aspnetcore.md) | string | ASP.NET Core exception middleware handling result | `handled`; `unhandled` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`error.type`](/docs/attributes-registry/error.md) | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`aspnetcore.diagnostics.handler.type`](/docs/attributes-registry/aspnetcore.md) | string | Full type name of the [`IExceptionHandler`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.diagnostics.iexceptionhandler) implementation that handled the exception. | `Contoso.MyHandler` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[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. + +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. + +**[2]:** if and only if the exception was handled by this handler. + +`aspnetcore.diagnostics.exception.result` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `handled` | Exception was handled by the exception handling middleware. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unhandled` | Exception was not handled by the exception handling middleware. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `skipped` | Exception handling was skipped because the response had started. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `aborted` | Exception handling didn't run because the request was aborted. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`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) | + + +## Rate-limiting + +All rate-limiting metrics are reported by the `Microsoft.AspNetCore.RateLimiting` meter. + +### Metric: `aspnetcore.rate_limiting.active_request_leases` + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `aspnetcore.rate_limiting.active_request_leases` | UpDownCounter | `{request}` | Number of requests that are currently active on the server that hold a rate limiting lease. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`aspnetcore.rate_limiting.policy`](/docs/attributes-registry/aspnetcore.md) | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | `Conditionally Required` [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** if the matched endpoint for the request had a rate-limiting policy. + + +### Metric: `aspnetcore.rate_limiting.request_lease.duration` + +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.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 | +| -------- | --------------- | ----------- | -------------- | --------- | +| `aspnetcore.rate_limiting.request_lease.duration` | Histogram | `s` | The duration of rate limiting lease held by requests on the server. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`aspnetcore.rate_limiting.policy`](/docs/attributes-registry/aspnetcore.md) | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | `Conditionally Required` [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** if the matched endpoint for the request had a rate-limiting policy. + + +### Metric: `aspnetcore.rate_limiting.queued_requests` + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `aspnetcore.rate_limiting.queued_requests` | UpDownCounter | `{request}` | Number of requests that are currently queued, waiting to acquire a rate limiting lease. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`aspnetcore.rate_limiting.policy`](/docs/attributes-registry/aspnetcore.md) | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | `Conditionally Required` [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** if the matched endpoint for the request had a rate-limiting policy. + + +### Metric: `aspnetcore.rate_limiting.request.time_in_queue` + +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.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 | +| -------- | --------------- | ----------- | -------------- | --------- | +| `aspnetcore.rate_limiting.request.time_in_queue` | Histogram | `s` | The time the request spent in a queue waiting to acquire a rate limiting lease. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`aspnetcore.rate_limiting.result`](/docs/attributes-registry/aspnetcore.md) | string | Rate-limiting result, shows whether the lease was acquired or contains a rejection reason | `acquired`; `request_canceled` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`aspnetcore.rate_limiting.policy`](/docs/attributes-registry/aspnetcore.md) | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | `Conditionally Required` [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** if the matched endpoint for the request had a rate-limiting policy. + +`aspnetcore.rate_limiting.result` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `acquired` | Lease was acquired | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `endpoint_limiter` | Lease request was rejected by the endpoint limiter | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `global_limiter` | Lease request was rejected by the global limiter | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `request_canceled` | Lease request was canceled | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +### Metric: `aspnetcore.rate_limiting.requests` + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `aspnetcore.rate_limiting.requests` | Counter | `{request}` | Number of requests that tried to acquire a rate limiting lease. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Requests could be: + +* Rejected by global or endpoint rate limiting policies +* Canceled while waiting for the lease. + +Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`aspnetcore.rate_limiting.result`](/docs/attributes-registry/aspnetcore.md) | string | Rate-limiting result, shows whether the lease was acquired or contains a rejection reason | `acquired`; `request_canceled` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`aspnetcore.rate_limiting.policy`](/docs/attributes-registry/aspnetcore.md) | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | `Conditionally Required` [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** if the matched endpoint for the request had a rate-limiting policy. + +`aspnetcore.rate_limiting.result` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `acquired` | Lease was acquired | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `endpoint_limiter` | Lease request was rejected by the endpoint limiter | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `global_limiter` | Lease request was rejected by the global limiter | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `request_canceled` | Lease request was canceled | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md new file mode 100644 index 0000000000..6b10c7e575 --- /dev/null +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -0,0 +1,57 @@ + + +# Semantic Conventions for DNS metrics emitted by .NET + +**Status**: [Stable][DocumentStatus] + +This article defines semantic conventions for DNS metrics emitted by .NET. + + + +- [DNS metrics](#dns-metrics) + - [Metric: `dns.lookup.duration`](#metric-dnslookupduration) + + + +## DNS metrics + +### Metric: `dns.lookup.duration` + +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.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 | +| -------- | --------------- | ----------- | -------------- | +| `dns.lookup.duration` | Histogram | `s` | Measures the time taken to perform a DNS lookup. [1] | + +**[1]:** Meter name: `System.Net.NameResolution`; Added in: .NET 8.0 + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `dns.question.name` | string | The name being queried. [1] | `www.example.com`; `dot.net` | Required | +| [`error.type`](../attributes-registry/error.md) | string | One of the resolution errors or the full name of exception type. [2] | `host_not_found`; `no_recovery`; `System.Net.Sockets.SocketException` | Conditionally Required: if and only if an error has occurred. | + +**[1]:** The name being queried. +If the name field contains non-printable characters (below 32 or above 126), those characters should be represented as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. Tabs, carriage returns, and line feeds should be converted to \t, \r, and \n respectively. + +**[2]:** The following errors codes are reported: + +- "host_not_found" +- "try_again" +- "address_family_not_supported" +- "no_recovery" + +See [SocketError](https://learn.microsoft.com/dotnet/api/system.net.sockets.socketerror) +for more details. + +`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 | +|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md new file mode 100644 index 0000000000..a203d433a6 --- /dev/null +++ b/docs/dotnet/dotnet-http-metrics.md @@ -0,0 +1,220 @@ + + +# Semantic Conventions for HTTP client and server metrics emitted by .NET + +**Status**: [Stable][DocumentStatus] + +This article defines semantic conventions for HTTP metrics emitted by .NET components and runtime. + + + +- [HTTP client](#http-client) + - [Metric: `http.client.request.duration`](#metric-httpclientrequestduration) + - [Metric: `http.client.open_connections`](#metric-httpclientopen_connections) + - [Metric: `http.client.connection.duration`](#metric-httpclientconnectionduration) + - [Metric: `http.client.request.time_in_queue`](#metric-httpclientrequesttime_in_queue) + - [Metric: `http.client.active_requests`](#metric-httpclientactive_requests) +- [HTTP server](#http-server) + - [Metric: `http.server.request.duration`](#metric-httpserverrequestduration) + - [Metric: `http.server.active_requests`](#metric-httpserveractive_requests) + + + +## HTTP client + +All Http client metrics are reported by the `System.Net.Http` meter. + +### Metric: `http.client.request.duration` + +Client request duration measures the time it takes to receive response headers and doesn't include time to read the response body. + +This metric follows the common [http.client.request.duration](../http/http-metrics.md#metric-httpclientrequestduration) definition. + +Notes: + +- Meter name is `System.Net.Http` +- Metric added in .NET 8.0 +- When the `error.type` attribute is reported, it contains one of [HTTP Request errors](https://learn.microsoft.com/dotnet/api/system.net.http.httprequesterror) in snake_case, a full exception type, or a string representation of received status code. +- `network.protocol.name` is not reported and should always be assumed to match `http`. +- `server.port` is not reported when it matches a default one for provided scheme (`443` for `https` and `80` for `http`) +- `url.scheme` is always reported. + +### Metric: `http.client.open_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.open_connections` | UpDownCounter | `{connection}` | Number of outbound HTTP connections that are currently active or idle on the client. [1] | + +**[1]:** Meter name: `System.Net.Http`; Added in: .NET 8.0 + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `http.connection.state` | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | Required | +| [`network.peer.address`](../attributes-registry/network.md) | string | Remote IP address of the socket connection. | `10.1.2.80` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | The negotiated version of the protocol associated with connection in the connection pool. [1] | `1.1`; `2`; `3` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | + +**[1]:** HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. So, the `network.protocol.version` value reported on connection metrics is different than the one reported on request-level metrics or spans for HTTP 1.0 requests. + +**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. + +**[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]:** If not the default (`80` for `http` scheme, `443` for `https`). + +`http.connection.state` MUST be one of the following: + +| Value | Description | +|---|---| +| `active` | active state. | +| `idle` | idle state. | + +### Metric: `http.client.connection.duration` + +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.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.connection.duration` | Histogram | `s` | The duration of the successfully established outbound HTTP connections. [1] | + +**[1]:** Meter name: `System.Net.Http`; Added in: .NET 8.0 + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | The negotiated version of the protocol associated with connection in the connection pool. [1] | `1.1`; `2`; `3` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | + +**[1]:** HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. So, the `network.protocol.version` value reported on connection metrics is different than the one reported on request-level metrics or spans for HTTP 1.0 requests. + +**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. + +**[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]:** If not the default (`80` for `http` scheme, `443` for `https`). + +### Metric: `http.client.request.time_in_queue` + +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.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 | +| -------- | --------------- | ----------- | -------------- | +| `http.client.request.time_in_queue` | Histogram | `s` | The amount of time requests spent on a queue waiting for an available connection. [1] | + +**[1]:** Meter name: `System.Net.Http`; Added in: .NET 8.0 + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | The negotiated version of the protocol associated with connection in the connection pool. [2] | `1.1`; `2`; `3` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | + +**[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). +If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. It's not possible at the moment to override the list of known HTTP methods. + +**[2]:** HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. So, the `network.protocol.version` value reported on connection metrics is different than the one reported on request-level metrics or spans for HTTP 1.0 requests. + +**[3]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. + +**[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]:** If not the default (`80` for `http` scheme, `443` for `https`). + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `CONNECT` | CONNECT method. | +| `DELETE` | DELETE method. | +| `GET` | GET method. | +| `HEAD` | HEAD method. | +| `OPTIONS` | OPTIONS method. | +| `PATCH` | PATCH method. | +| `POST` | POST method. | +| `PUT` | PUT method. | +| `TRACE` | TRACE method. | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | + +### Metric: `http.client.active_requests` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.active_requests` | UpDownCounter | `{request}` | Number of active HTTP requests. [1] | + +**[1]:** Meter name: `System.Net.Http`; Added in: .NET 8.0 + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | + +**[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). +If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. It's not possible at the moment to override the list of known HTTP methods. + +**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. + +**[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]:** If not the default (`80` for `http` scheme, `443` for `https`). + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `CONNECT` | CONNECT method. | +| `DELETE` | DELETE method. | +| `GET` | GET method. | +| `HEAD` | HEAD method. | +| `OPTIONS` | OPTIONS method. | +| `PATCH` | PATCH method. | +| `POST` | POST method. | +| `PUT` | PUT method. | +| `TRACE` | TRACE method. | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | + +## HTTP server + +All HTTP server metrics are reported by the `Microsoft.AspNetCore.Hosting` meter. + +### Metric: `http.server.request.duration` + +Measures time to last byte. This metric follows the common [http.server.request.duration](../http/http-metrics.md#metric-httpserverrequestduration) definition. + +Notes: + +- Meter name is `Microsoft.AspNetCore.Hosting` +- Metric added in ASP.NET Core 8.0 +- Opt-in `server.address` and `server.port` attributes are not reported +- Additional attributes: + + - The `aspnetcore.request.is_unhandled` boolean attribute is reported when the request was **not** handled by the application pipeline. It's skipped otherwise. + +### Metric: `http.server.active_requests` + +Measures the number of HTTP requests that are currently active on the server. This metric follows the common [http.server.active_requests](../http/http-metrics.md#metric-httpserveractive_requests) definition. + +Notes: + +- Meter name is `Microsoft.AspNetCore.Hosting` +- Opt-in `server.address` and `server.port` attributes are not reported +- Metric added in ASP.NET Core 8.0 + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md new file mode 100644 index 0000000000..29456e409e --- /dev/null +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -0,0 +1,452 @@ + + +# Semantic Conventions for Kestrel web server metrics + +**Status**: [Stable][DocumentStatus] + +This article defines semantic conventions for Kestrel web server. + + + +- [Kestrel endpoint](#kestrel-endpoint) +- [Metric: `kestrel.active_connections`](#metric-kestrelactive_connections) +- [Metric: `kestrel.connection.duration`](#metric-kestrelconnectionduration) +- [Metric: `kestrel.rejected_connections`](#metric-kestrelrejected_connections) +- [Metric: `kestrel.queued_connections`](#metric-kestrelqueued_connections) +- [Metric: `kestrel.queued_requests`](#metric-kestrelqueued_requests) +- [Metric: `kestrel.upgraded_connections`](#metric-kestrelupgraded_connections) +- [Metric: `kestrel.tls_handshake.duration`](#metric-kestreltls_handshakeduration) +- [Metric: `kestrel.active_tls_handshakes`](#metric-kestrelactive_tls_handshakes) + + + +## Kestrel endpoint + +Kestrel endpoint is represented with [`System.Net.EndPoint`](https://learn.microsoft.com/dotnet/api/system.net.endpoint) class, which does not always provide information about server address or port. + +Instrumentation supports `IPEndPoint`, `UnixDomainSocketEndPoint`, and `NamedPipeEndPoint` and sets the `server.address`, `server.port` (for IP endpoint), `network.type`, and `network.transport` attributes from the corresponding endpoint on Kestrel metrics. + +In case instrumentation does not recognize `EndPoint` implementation, it sets the `server.address` attribute to `endpoint.ToString()` value and `network.transport` value to corresponding `endpoint.AddressFamily` property. + +## Metric: `kestrel.active_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `kestrel.active_connections` | UpDownCounter | `{connection}` | Number of connections that are currently active on the server. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.type`](/docs/attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | `Recommended` if the transport is `tcp` or `udp` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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. [4] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[2]:** The value SHOULD be normalized to lowercase. + +**[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. + +**[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. + +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +## Metric: `kestrel.connection.duration` + +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.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `kestrel.connection.duration` | Histogram | `s` | The duration of connections on the server. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`error.type`](/docs/attributes-registry/error.md) | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | `Conditionally Required` if and only if an error has occurred. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [2] | `http`; `web_sockets` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [3] | `1.1`; `2` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [4] | `tcp`; `unix` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.type`](/docs/attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [5] | `ipv4`; `ipv6` | `Recommended` if the transport is `tcp` or `udp` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`tls.protocol.version`](/docs/attributes-registry/tls.md) | string | Numeric part of the version parsed from the original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) | `1.2`; `3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Captures the exception type when a connection fails. + +**[2]:** The value SHOULD be normalized to lowercase. + +**[3]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. + +**[4]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[5]:** The value SHOULD be normalized to lowercase. + +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + +**[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) | + +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +## Metric: `kestrel.rejected_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `kestrel.rejected_connections` | Counter | `{connection}` | Number of connections rejected by the server. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Connections are rejected when the currently active count exceeds the value configured with `MaxConcurrentConnections`. +Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.type`](/docs/attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | `Recommended` if the transport is `tcp` or `udp` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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. [4] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[2]:** The value SHOULD be normalized to lowercase. + +**[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. + +**[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. + +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +## Metric: `kestrel.queued_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `kestrel.queued_connections` | UpDownCounter | `{connection}` | Number of connections that are currently queued and are waiting to start. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.type`](/docs/attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | `Recommended` if the transport is `tcp` or `udp` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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. [4] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[2]:** The value SHOULD be normalized to lowercase. + +**[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. + +**[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. + +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +## Metric: `kestrel.queued_requests` + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `kestrel.queued_requests` | UpDownCounter | `{request}` | Number of HTTP requests on multiplexed connections (HTTP/2 and HTTP/3) that are currently queued and are waiting to start. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `http`; `web_sockets` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [2] | `1.1`; `2` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `unix` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.type`](/docs/attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | `Recommended` if the transport is `tcp` or `udp` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** The value SHOULD be normalized to lowercase. + +**[2]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. + +**[3]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[4]:** The value SHOULD be normalized to lowercase. + +**[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. + +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +## Metric: `kestrel.upgraded_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `kestrel.upgraded_connections` | UpDownCounter | `{connection}` | Number of connections that are currently upgraded (WebSockets). . [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** The counter only tracks HTTP/1.1 connections. + +Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.type`](/docs/attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | `Recommended` if the transport is `tcp` or `udp` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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. [4] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[2]:** The value SHOULD be normalized to lowercase. + +**[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. + +**[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. + +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +## Metric: `kestrel.tls_handshake.duration` + +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.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 | +| -------- | --------------- | ----------- | -------------- | --------- | +| `kestrel.tls_handshake.duration` | Histogram | `s` | The duration of TLS handshakes on the server. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`error.type`](/docs/attributes-registry/error.md) | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | `Conditionally Required` if and only if an error has occurred. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [2] | `tcp`; `unix` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.type`](/docs/attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [3] | `ipv4`; `ipv6` | `Recommended` if the transport is `tcp` or `udp` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [5] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`tls.protocol.version`](/docs/attributes-registry/tls.md) | string | Numeric part of the version parsed from the original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) | `1.2`; `3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Captures the exception type when a TLS handshake fails. + +**[2]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[3]:** The value SHOULD be normalized to lowercase. + +**[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. + +**[5]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +`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) | + +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +## Metric: `kestrel.active_tls_handshakes` + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `kestrel.active_tls_handshakes` | UpDownCounter | `{handshake}` | Number of TLS handshakes that are currently in progress on the server. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.type`](/docs/attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | `Recommended` if the transport is `tcp` or `udp` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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. [4] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[2]:** The value SHOULD be normalized to lowercase. + +**[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. + +**[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. + +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md new file mode 100644 index 0000000000..c9c1e99974 --- /dev/null +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -0,0 +1,88 @@ + + +# Semantic Conventions for SignalR server metrics + +**Status**: [Stable][DocumentStatus] + +This article defines semantic conventions for SignalR metrics emitted by .NET components and runtime. + + + +- [Metric: `signalr.server.connection.duration`](#metric-signalrserverconnectionduration) +- [Metric: `signalr.server.active_connections`](#metric-signalrserveractive_connections) + + + +## Metric: `signalr.server.connection.duration` + +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.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `signalr.server.connection.duration` | Histogram | `s` | The duration of connections on the server. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Meter name: `Microsoft.AspNetCore.Http.Connections`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`signalr.connection.status`](/docs/attributes-registry/signalr.md) | string | SignalR HTTP connection closure status. | `app_shutdown`; `timeout` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`signalr.transport`](/docs/attributes-registry/signalr.md) | string | [SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md) | `web_sockets`; `long_polling` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`signalr.connection.status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `normal_closure` | The connection was closed normally. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `timeout` | The connection was closed due to a timeout. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `app_shutdown` | The connection was closed because the app is shutting down. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`signalr.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `server_sent_events` | ServerSentEvents protocol | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `long_polling` | LongPolling protocol | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `web_sockets` | WebSockets protocol | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +## Metric: `signalr.server.active_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `signalr.server.active_connections` | UpDownCounter | `{connection}` | Number of connections that are currently active on the server. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Meter name: `Microsoft.AspNetCore.Http.Connections`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`signalr.connection.status`](/docs/attributes-registry/signalr.md) | string | SignalR HTTP connection closure status. | `app_shutdown`; `timeout` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`signalr.transport`](/docs/attributes-registry/signalr.md) | string | [SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md) | `web_sockets`; `long_polling` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`signalr.connection.status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `normal_closure` | The connection was closed normally. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `timeout` | The connection was closed due to a timeout. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `app_shutdown` | The connection was closed because the app is shutting down. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`signalr.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `server_sent_events` | ServerSentEvents protocol | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `long_polling` | LongPolling protocol | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `web_sockets` | WebSockets protocol | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/exceptions/README.md b/docs/exceptions/README.md index e4bd767b8c..91f6c88305 100644 --- a/docs/exceptions/README.md +++ b/docs/exceptions/README.md @@ -1,13 +1,13 @@ # Semantic Conventions for Exceptions -**Status**: [Experimental][DocumentStatus] +**Status**: [Stable][DocumentStatus] This document defines semantic conventions for Exceptions. @@ -16,4 +16,4 @@ Semantic conventions for Exceptions are defined for the following signals: * [Exceptions on spans](exceptions-spans.md): Semantic Conventions for Exceptions associated with *spans*. * [Exceptions in logs](exceptions-logs.md): Semantic Conventions for Exceptions recorded in *logs*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/exceptions/exceptions-logs.md b/docs/exceptions/exceptions-logs.md index 32d20e68cf..ba4f9b1ea6 100644 --- a/docs/exceptions/exceptions-logs.md +++ b/docs/exceptions/exceptions-logs.md @@ -4,24 +4,24 @@ linkTitle: Logs # Semantic Conventions for Exceptions in Logs -**Status**: [Experimental][DocumentStatus] +**Status**: [Stable][DocumentStatus] This document defines semantic conventions for recording exceptions on -[logs](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/bridge-api.md#emit-a-logrecord) and [events](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/event-api.md#emit-event) -emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/bridge-api.md#logger). +[logs](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/logs/bridge-api.md#emit-a-logrecord) and [events](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/logs/event-api.md#emit-event) +emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/logs/bridge-api.md#logger). - [Recording an Exception](#recording-an-exception) - [Attributes](#attributes) - * [Stacktrace Representation](#stacktrace-representation) + - [Stacktrace Representation](#stacktrace-representation) ## Recording an Exception Exceptions SHOULD be recorded as attributes on the -[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/bridge-api.md#logger) emit +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/logs/bridge-api.md#logger) emit operations. Exceptions MAY be recorded on "logs" or "events" depending on the context. @@ -33,19 +33,18 @@ the language runtime. ## Attributes The table below indicates which attributes should be added to the -[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below | -| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | Recommended | -| `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | See below | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`exception.message`](/docs/attributes-registry/exception.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | `Conditionally Required` [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`exception.type`](/docs/attributes-registry/exception.md) | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`exception.stacktrace`](/docs/attributes-registry/exception.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**Additional attribute requirements:** At least one of the following sets of attributes is required: +**[1]:** Required if `exception.type` is not set, recommended otherwise. -* `exception.type` -* `exception.message` +**[2]:** Required if `exception.message` is not set, recommended otherwise. ### Stacktrace Representation @@ -53,4 +52,4 @@ The table below indicates which attributes should be added to the Same as [Trace Semantic Conventions for Exceptions - Stacktrace Representation](exceptions-spans.md#stacktrace-representation). -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md index eef07f2cdb..5c744f2c12 100644 --- a/docs/exceptions/exceptions-spans.md +++ b/docs/exceptions/exceptions-spans.md @@ -4,7 +4,7 @@ linkTitle: Spans # Semantic Conventions for Exceptions on Spans -**Status**: [Experimental][DocumentStatus] +**Status**: [Stable][DocumentStatus] This document defines semantic conventions for recording application exceptions associated with spans. @@ -13,7 +13,7 @@ exceptions associated with spans. - [Recording an Exception](#recording-an-exception) - [Attributes](#attributes) - * [Stacktrace Representation](#stacktrace-representation) + - [Stacktrace Representation](#stacktrace-representation) @@ -23,7 +23,7 @@ An exception SHOULD be recorded as an `Event` on the span during which it occurr The name of the event MUST be `"exception"`. A typical template for an auto-instrumentation implementing this semantic convention -using an [API-provided `recordException` method](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#record-exception) +using an [API-provided `recordException` method](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/trace/api.md#record-exception) could look like this (pseudo-Java): ```java @@ -44,16 +44,20 @@ The table below indicates which attributes should be added to the `Event` and their types. -The event name MUST be `exception`. +The event name MUST be `exception` -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `exception.escaped` | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] | | Recommended | -| `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below | -| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | Recommended | -| `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | See below | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`exception.message`](/docs/attributes-registry/exception.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | `Conditionally Required` [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`exception.type`](/docs/attributes-registry/exception.md) | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`exception.escaped`](/docs/attributes-registry/exception.md) | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [3] | | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`exception.stacktrace`](/docs/attributes-registry/exception.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** An exception is considered to have escaped (or left) the scope of a span, +**[1]:** Required if `exception.type` is not set, recommended otherwise. + +**[2]:** Required if `exception.message` is not set, recommended otherwise. + +**[3]:** An exception is considered to have escaped (or left) the scope of a span, if that span is ended while the exception is still logically "in flight". This may be actually "in flight" in some languages (e.g. if the exception is passed to a Context manager's `__exit__` method in Python) but will @@ -63,17 +67,12 @@ It is usually not possible to determine at the point where an exception is throw whether it will escape the scope of a span. However, it is trivial to know that an exception will escape, if one checks for an active exception just before ending the span, -as done in the [example above](#recording-an-exception). +as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). It follows that an exception may still escape the scope of the span even if the `exception.escaped` attribute was not set or set to false, since the event might have been recorded at a time where it was not clear whether the exception will escape. - -**Additional attribute requirements:** At least one of the following sets of attributes is required: - -* `exception.type` -* `exception.message` ### Stacktrace Representation @@ -104,9 +103,9 @@ grained information from a stacktrace, if necessary. [python-stacktrace]: https://docs.python.org/3/library/traceback.html#traceback.format_exc [js-stacktrace]: https://v8.dev/docs/stack-trace-api [ruby-full-message]: https://ruby-doc.org/core-2.7.1/Exception.html#method-i-full_message -[csharp-stacktrace]: https://docs.microsoft.com/en-us/dotnet/api/system.exception.tostring +[csharp-stacktrace]: https://docs.microsoft.com/dotnet/api/system.exception.tostring [go-stacktrace]: https://pkg.go.dev/runtime/debug#Stack [telemetry-sdk-resource]: ../resource/README.md#telemetry-sdk [erlang-stacktrace]: https://www.erlang.org/doc/man/erl_error.html#format_exception-3 [elixir-stacktrace]: https://hexdocs.pm/elixir/1.14.3/Exception.html#format/3 -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/faas/README.md b/docs/faas/README.md index 62ecf24d24..760672a0f6 100644 --- a/docs/faas/README.md +++ b/docs/faas/README.md @@ -1,7 +1,7 @@ @@ -20,4 +20,4 @@ Technology specific semantic conventions are defined for the following FaaS serv * [AWS Lambda](aws-lambda.md): Semantic Conventions for *AWS Lambda*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 41ccb4cce5..c7bd757411 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -14,16 +14,18 @@ use cases. - [All triggers](#all-triggers) - * [AWS X-Ray Environment Span Link](#aws-x-ray-environment-span-link) + - [AWS X-Ray Active Tracing Considerations](#aws-x-ray-active-tracing-considerations) + - [`xray-lambda` Propagator Functionality](#xray-lambda-propagator-functionality) + - [`xray-lambda` Propagator Configuration](#xray-lambda-propagator-configuration) - [API Gateway](#api-gateway) - [SQS](#sqs) - * [SQS Event](#sqs-event) - * [SQS Message](#sqs-message) + - [SQS Event](#sqs-event) + - [SQS Message](#sqs-message) - [Examples](#examples) - * [API Gateway Request Proxy (Lambda tracing passive)](#api-gateway-request-proxy-lambda-tracing-passive) - * [API Gateway Request Proxy (Lambda tracing active)](#api-gateway-request-proxy-lambda-tracing-active) - * [SQS (Lambda tracing passive)](#sqs-lambda-tracing-passive) - * [SQS (Lambda tracing active)](#sqs-lambda-tracing-active) + - [API Gateway Request Proxy (Lambda tracing passive)](#api-gateway-request-proxy-lambda-tracing-passive) + - [API Gateway Request Proxy (Lambda tracing active)](#api-gateway-request-proxy-lambda-tracing-active) + - [SQS (Lambda tracing passive)](#sqs-lambda-tracing-passive) + - [SQS (Lambda tracing active)](#sqs-lambda-tracing-active) - [Resource Detector](#resource-detector) @@ -43,9 +45,9 @@ Also consider setting other attributes of the [`faas` resource][faasres] and [tr and the [cloud resource conventions][cloud]. The following AWS Lambda-specific attribute MAY also be set: -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.lambda.invoked_arn` | string | The full invoked ARN as provided on the `Context` passed to the function (`Lambda-Runtime-Invoked-Function-Arn` header on the `/runtime/invocation/next` applicable). [1] | `arn:aws:lambda:us-east-1:123456:function:myfunction:myalias` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`aws.lambda.invoked_arn`](/docs/attributes-registry/aws.md) | string | The full invoked ARN as provided on the `Context` passed to the function (`Lambda-Runtime-Invoked-Function-Arn` header on the `/runtime/invocation/next` applicable). [1] | `arn:aws:lambda:us-east-1:123456:function:myfunction:myalias` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** This may be different from `cloud.resource_id` if an alias is involved. @@ -54,21 +56,63 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a [faasres]: /docs/resource/faas.md (FaaS resource conventions) [cloud]: /docs/resource/cloud.md (Cloud resource conventions) -### AWS X-Ray Environment Span Link +### AWS X-Ray Active Tracing Considerations -If the `_X_AMZN_TRACE_ID` environment variable is set, instrumentation SHOULD try to parse an -OpenTelemetry `Context` out of it using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/context/api-propagators.md). If the -resulting `Context` is [valid](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#isvalid) then a [Span Link][] SHOULD be added to the new Span's -[start options](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#specifying-links) with an associated attribute of `source=x-ray-env` to -indicate the source of the linked span. -Instrumentation MUST check if the context is valid before using it because the `_X_AMZN_TRACE_ID` environment variable can -contain an incomplete trace context which indicates X-Ray isn’t enabled. The environment variable will be set and the -`Context` will be valid and sampled only if AWS X-Ray has been enabled for the Lambda function. A user can -disable AWS X-Ray for the function if the X-Ray Span Link is not desired. +When [AWS X-Ray Active Tracing](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html) is enabled for a Lambda, +the runtime will automatically generate a span based on configured sampling rates and propagate the span context +via the `_X_AMZN_TRACE_ID` environment variable (and the `com.amazonaws.xray.traceHeader` system property for Java Lambda functions). +This span context is encoded using the [X-Ray Tracing Header Format](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader). -**Note**: When instrumenting a Java AWS Lambda, instrumentation SHOULD first try to parse an OpenTelemetry `Context` out of the system property `com.amazonaws.xray.traceHeader` using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md) before checking and attempting to parse the environment variable above. +Users MUST be able to [configure the propagator](#xray-lambda-propagator-configuration) to prioritize propagating this X-Ray "Active Tracing" span context. +(FYI: Users probably want this enabled if OpenTelemetry is configured to report spans to AWS X-Ray so their trace is linked together properly.) -[Span Link]: https://opentelemetry.io/docs/concepts/signals/traces/#span-links +#### `xray-lambda` Propagator Functionality + +SDK's that have instrumentation for AWS Lambda SHOULD provide an additional propagator alongside the X-Ray propagator +that can [be configured](#xray-lambda-propagator-configuration) via the `OTEL_PROPAGATORS` environment variable setting as `xray-lambda`. +This propagator is expected to replace the `xray` propagator in the `OTEL_PROPAGATORS` list. The behavior for this propagator is described in pseudo code below. + +``` +extract(context, carrier) { + xrayContext = xrayPropagator.extract(context, carrier) + + // To avoid potential issues when extracting with an active span context (such as with a span link), + // the `xray-lambda` propagator SHOULD check if the provided context already has an active span context. + // If found, the propagator SHOULD just return the extract result of the `xray` propagator. + if (Span.fromContext(context).getSpanContext().isValid()) + return xrayContext + + // If xray-lambda environment variable not set, return the xray extract result. + traceHeader = getEnvironment("_X_AMZN_TRACE_ID") + if (isEmptyOrNull(traceHeader)) + return xrayContext + + // Apply the xray propagator using the span context contained in the xray-lambda environment variable. + return xrayPropagator.extract(xrayContext, ["X-Amzn-Trace-Id": traceHeader]) +} +``` + +*Note:* Java implementations should use the system property value of the key `com.amazonaws.xray.traceHeader` +instead of the environment variable if the system property is not empty. + +#### `xray-lambda` Propagator Configuration + +**When reporting spans to AWS X-Ray** from AWS Lambda, the `xray-lambda` propagator SHOULD replace the `xray` propagator in the `OTEL_PROPAGATORS` configuration. Including both will prevent `xray-lambda` from functioning properly. + +Example valid configuration when reporting spans to AWS X-Ray: + +- `OTEL_PROPAGATORS=tracecontext,baggage,xray-lambda` + +Example invalid configurations: + +- `OTEL_PROPAGATORS=tracecontext,baggage,xray,xray-lambda` +- `OTEL_PROPAGATORS=tracecontext,baggage,xray-lambda,xray` + +**When OpenTelemetry is reporting traces to another system besides AWS X-Ray**, users SHOULD NOT use `xray-lambda` or reported traces will be broken. + +Example valid configuration when OpenTelemetry is reporting traces to another system besides AWS X-Ray: + +- `OTEL_PROPAGATORS=tracecontext,baggage,xray` ## API Gateway @@ -109,26 +153,26 @@ be ` process`. If there are multiple sources in the batch, the nam For every message in the event, the [message system attributes][] (not message attributes, which are provided by the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be -parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/context/api-propagators.md) and +parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/context/api-propagators.md) and added as a link to the span. This means the span may have as many links as messages in the batch. See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info. - [`faas.trigger`][faas] MUST be set to `pubsub`. -- [`messaging.operation`](/docs/messaging/messaging-spans.md) MUST be set to `process`. -- [`messaging.system`](/docs/messaging/messaging-spans.md) MUST be set to `AmazonSQS`. +- [`messaging.operation.type`](/docs/messaging/messaging-spans.md) MUST be set to `process`. +- [`messaging.system`](/docs/messaging/messaging-spans.md) MUST be set to `aws_sqs`. ### SQS Message For the SQS message span, the name MUST be ` process`. The parent MUST be the `CONSUMER` span corresponding to the SQS event. The [message system attributes][] (not message attributes, which are provided by the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be -parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/context/api-propagators.md) and +parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/context/api-propagators.md) and added as a link to the span. See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info. - [`faas.trigger`][faas] MUST be set to `pubsub`. -- [`messaging.operation`](/docs/messaging/messaging-spans.md#messaging-attributes) MUST be set to `process`. -- [`messaging.system`](/docs/messaging/messaging-spans.md#messaging-attributes) MUST be set to `AmazonSQS`. +- [`messaging.operation.type`](/docs/messaging/messaging-spans.md#messaging-attributes) MUST be set to `process`. +- [`messaging.system`](/docs/messaging/messaging-spans.md#messaging-attributes) MUST be set to `aws_sqs`. Other [Messaging attributes](/docs/messaging/messaging-spans.md#messaging-attributes) SHOULD be set based on the available information in the SQS message event. @@ -207,9 +251,9 @@ Function F: | Span ProcBatch | | Links | | | | Span Prod1 | Span Prod2 | | SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` | `CONSUMER` | `CONSUMER` | | Status | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` | -| `messaging.system` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | +| `messaging.system` | `aws_sqs` | `aws_sqs` | `aws_sqs` | `aws_sqs` | `aws_sqs` | | `messaging.destination.name` | `Q` | `Q` | `Q` | `Q` | `Q` | -| `messaging.operation` | | | `process` | `process` | `process` | +| `messaging.operation.type` | | | `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 @@ -246,4 +290,4 @@ because it is not available until function invocation. [environment variables]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md index 376ec3dc7d..104b34c9bd 100644 --- a/docs/faas/faas-metrics.md +++ b/docs/faas/faas-metrics.md @@ -13,61 +13,279 @@ The conventions described in this section are FaaS (function as a service) speci metric events about those operations will be generated and reported to provide insights into the operations. By adding FaaS attributes to metric events it allows for finely tuned filtering. -**Disclaimer:** These are initial FaaS metric instruments and attributes but more may be added in the future. - - [Metric Instruments](#metric-instruments) - * [FaaS Invocations](#faas-invocations) -- [Attributes](#attributes) + - [FaaS Instance](#faas-instance) + - [Metric: `faas.invoke_duration`](#metric-faasinvoke_duration) + - [Metric: `faas.init_duration`](#metric-faasinit_duration) + - [Metric: `faas.coldstarts`](#metric-faascoldstarts) + - [Metric: `faas.errors`](#metric-faaserrors) + - [Metric: `faas.invocations`](#metric-faasinvocations) + - [Metric: `faas.timeouts`](#metric-faastimeouts) + - [Metric: `faas.mem_usage`](#metric-faasmem_usage) + - [Metric: `faas.cpu_usage`](#metric-faascpu_usage) + - [Metric: `faas.net_io`](#metric-faasnet_io) - [References](#references) - * [Metric References](#metric-references) + - [Metric References](#metric-references) ## Metric Instruments -The following metric instruments MUST be used to describe FaaS operations. They MUST be of the specified -type and units. +The following metric instruments describe FaaS operations. + +### FaaS Instance + +The following metrics are recorded by the FaaS instance. + +#### Metric: `faas.invoke_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-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 | +| -------- | --------------- | ----------- | -------------- | --------- | +| `faas.invoke_duration` | Histogram | `s` | Measures the duration of the function's logic execution | ![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 | +|---|---|---|---|---|---| +| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http` | To provide an answer to an inbound HTTP request | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `timer` | A function is scheduled to be executed regularly | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other` | If none of the others apply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +#### Metric: `faas.init_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-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 | +| -------- | --------------- | ----------- | -------------- | --------- | +| `faas.init_duration` | Histogram | `s` | Measures the duration of the function's initialization, such as a cold start | ![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 | +|---|---|---|---|---|---| +| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http` | To provide an answer to an inbound HTTP request | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `timer` | A function is scheduled to be executed regularly | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other` | If none of the others apply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +#### Metric: `faas.coldstarts` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `faas.coldstarts` | Counter | `{coldstart}` | Number of invocation cold starts | ![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 | +|---|---|---|---|---|---| +| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http` | To provide an answer to an inbound HTTP request | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `timer` | A function is scheduled to be executed regularly | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other` | If none of the others apply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +#### Metric: `faas.errors` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `faas.errors` | Counter | `{error}` | Number of invocation errors | ![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 | +|---|---|---|---|---|---| +| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http` | To provide an answer to an inbound HTTP request | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `timer` | A function is scheduled to be executed regularly | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other` | If none of the others apply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +#### Metric: `faas.invocations` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `faas.invocations` | Counter | `{invocation}` | Number of successful invocations | ![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 | +|---|---|---|---|---|---| +| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http` | To provide an answer to an inbound HTTP request | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `timer` | A function is scheduled to be executed regularly | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other` | If none of the others apply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +#### Metric: `faas.timeouts` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `faas.timeouts` | Counter | `{timeout}` | Number of invocation timeouts | ![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 | +|---|---|---|---|---|---| +| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http` | To provide an answer to an inbound HTTP request | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `timer` | A function is scheduled to be executed regularly | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other` | If none of the others apply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +#### Metric: `faas.mem_usage` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `faas.mem_usage` | Histogram | `By` | Distribution of max memory usage per invocation | ![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 | +|---|---|---|---|---|---| +| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http` | To provide an answer to an inbound HTTP request | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `timer` | A function is scheduled to be executed regularly | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other` | If none of the others apply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +#### Metric: `faas.cpu_usage` + +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-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 | +| -------- | --------------- | ----------- | -------------- | --------- | +| `faas.cpu_usage` | Histogram | `s` | Distribution of CPU usage per invocation | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + -### FaaS Invocations + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -Below is a table of FaaS invocation metric instruments. +`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | -|------------------------|---------------------------------------------------|--------------|-------------------------------------------|------------------------------------------------------------------------------| -| `faas.invoke_duration` | Histogram | milliseconds | `ms` | Measures the duration of the invocation | -| `faas.init_duration` | Histogram | milliseconds | `ms` | Measures the duration of the function's initialization, such as a cold start | -| `faas.coldstarts` | Counter | default unit | `{coldstart}` | Number of invocation cold starts. | -| `faas.errors` | Counter | default unit | `{error}` | Number of invocation errors. | -| `faas.invocations` | Counter | default unit | `{invocation}` | Number of successful invocations. | -| `faas.timeouts` | Counter | default unit | `{timeout}` | Number of invocation timeouts. | +| Value | Description | Stability | +|---|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http` | To provide an answer to an inbound HTTP request | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `timer` | A function is scheduled to be executed regularly | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other` | If none of the others apply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + -Optionally, when applicable: +#### Metric: `faas.net_io` -| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | -|------------------|---------------------------------------------------|--------------|-------------------------------------------|-------------------------------------------------| -| `faas.mem_usage` | Histogram | Bytes | `By` | Distribution of max memory usage per invocation | -| `faas.cpu_usage` | Histogram | milliseconds | `ms` | Distribution of CPU usage per invocation | -| `faas.net_io` | Histogram | Bytes | `By` | Distribution of net I/O usage per invocation | +This metric is [recommended][MetricRecommended]. -## Attributes + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `faas.net_io` | Histogram | `By` | Distribution of net I/O usage per invocation | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + -Below is a table of the attributes to be included on FaaS metric events. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| Name | Requirement Level | Notes and examples | -|-------------------------|-------------------|--------------------------------------------------------------------------------------------------------------------------| -| `faas.trigger` | Required | Type of the trigger on which the function is invoked. SHOULD be one of: `datasource`, `http`, `pubsub`, `timer`, `other` | -| `faas.invoked_name` | Required | Name of the invoked function. Example: `my-function` | -| `faas.invoked_provider` | Required | Cloud provider of the invoked function. Corresponds to the resource `cloud.provider`. Example: `aws` | -| `faas.invoked_region` | Required | Cloud provider region of invoked function. Corresponds to resource `cloud.region`. Example: `us-east-1` | +`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -More details on these attributes, the function name and the difference compared to the faas.invoked_name can be found at the related [FaaS tracing specification](faas-spans.md). -For incoming FaaS invocations, the function for which metrics are reported is already described by its [FaaS resource attributes](../resource/faas.md). -Outgoing FaaS invocations are identified using the `faas.invoked_*` attributes above. -`faas.trigger` SHOULD be included in all metric events while `faas.invoked_*` attributes apply on outgoing FaaS invocation events only. +| Value | Description | Stability | +|---|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http` | To provide an answer to an inbound HTTP request | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `timer` | A function is scheduled to be executed regularly | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other` | If none of the others apply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + ## References @@ -82,4 +300,5 @@ FaaS providers. This list is not exhaustive. * [Google CloudFunctions Metrics](https://cloud.google.com/monitoring/api/metrics_gcp#gcp-cloudfunctions) * [OpenFaas Metrics](https://docs.openfaas.com/architecture/metrics/) -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[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/faas/faas-spans.md b/docs/faas/faas-spans.md index 2a06a3c1ec..afa1516c86 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -16,18 +16,18 @@ See also the [additional instructions for instrumenting AWS Lambda](aws-lambda.m - [General Attributes](#general-attributes) - * [Function Name](#function-name) - * [Difference between invocation and instance](#difference-between-invocation-and-instance) + - [Function Name](#function-name) + - [Difference between invocation and instance](#difference-between-invocation-and-instance) - [Incoming Invocations](#incoming-invocations) - * [Incoming FaaS Span attributes](#incoming-faas-span-attributes) - * [Resource attributes as incoming FaaS span attributes](#resource-attributes-as-incoming-faas-span-attributes) + - [Incoming FaaS Span attributes](#incoming-faas-span-attributes) + - [Resource attributes as incoming FaaS span attributes](#resource-attributes-as-incoming-faas-span-attributes) - [Outgoing Invocations](#outgoing-invocations) - [Function Trigger Type](#function-trigger-type) - * [Datasource](#datasource) - * [HTTP](#http) - * [PubSub](#pubsub) - * [Timer](#timer) - * [Other](#other) + - [Datasource](#datasource) + - [HTTP](#http) + - [PubSub](#pubsub) + - [Timer](#timer) + - [Other](#other) - [Example](#example) @@ -38,24 +38,14 @@ Span `name` should be set to the function name being executed. Depending on the If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../resource/faas.md). - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. [1] | `datasource` | Recommended | -| `faas.invocation_id` | string | The invocation ID of the current function invocation. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | Recommended | -| [`cloud.resource_id`](../resource/cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [2] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`cloud.resource_id`](/docs/attributes-registry/cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [1] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`faas.invocation_id`](/docs/attributes-registry/faas.md) | string | The invocation ID of the current function invocation. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. [2] | `datasource`; `http`; `pubsub` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** For the server/consumer span on the incoming side, -`faas.trigger` MUST be set. - -Clients invoking FaaS instances usually cannot set `faas.trigger`, -since they would typically need to look in the payload to determine -the event type. If clients set it, it should be the same as the -trigger that corresponding incoming would have (i.e., this has -nothing to do with the underlying transport used to make the API -call to invoke the lambda, which is often HTTP). - -**[2]:** On some cloud providers, it may not be possible to determine the full ID at startup, +**[1]:** On some cloud providers, it may not be possible to determine the full ID at startup, so it may be necessary to set `cloud.resource_id` as a span attribute instead. The exact value to use for `cloud.resource_id` depends on the cloud provider. @@ -67,21 +57,31 @@ The following well-known definitions MUST be used if you set this attribute and with the resolved function version, as the same runtime instance may be invokable with multiple different aliases. * **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) -* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id) of the invoked function, +* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/rest/api/resources/resources/get-by-id) of the invoked function, *not* the function app, having the form `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/`. This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share a TracerProvider. -`faas.trigger` MUST be one of the following: +**[2]:** For the server/consumer span on the incoming side, +`faas.trigger` MUST be set. -| Value | Description | -|---|---| -| `datasource` | A response to some data source operation such as a database or filesystem read/write. | -| `http` | To provide an answer to an inbound HTTP request | -| `pubsub` | A function is set to be executed when messages are sent to a messaging system. | -| `timer` | A function is scheduled to be executed regularly. | -| `other` | If none of the others apply | +Clients invoking FaaS instances usually cannot set `faas.trigger`, +since they would typically need to look in the payload to determine +the event type. If clients set it, it should be the same as the +trigger that corresponding incoming would have (i.e., this has +nothing to do with the underlying transport used to make the API +call to invoke the lambda, which is often HTTP). + +`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http` | To provide an answer to an inbound HTTP request | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `timer` | A function is scheduled to be executed regularly | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other` | If none of the others apply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ### Function Name @@ -108,7 +108,7 @@ The span attribute `faas.invocation_id` differs from the [resource attribute][Fa - `faas.instance` refers to the execution environment ID of the function. [AWS lambda]: https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html -[Azure functions]: https://docs.microsoft.com/en-us/azure/azure-functions/manage-connections#static-clients +[Azure functions]: https://docs.microsoft.com/azure/azure-functions/manage-connections#static-clients [Google functions]: https://cloud.google.com/functions/docs/concepts/exec#function_scope_versus_global_scope ## Incoming Invocations @@ -120,10 +120,10 @@ For incoming FaaS spans, the span kind MUST be `Server`. ### Incoming FaaS Span attributes -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `faas.coldstart` | boolean | A boolean that is true if the serverless function is executed for the first time (aka cold-start). | | Recommended | -| `faas.trigger` | string | Type of the trigger which caused this function invocation. [1] | `datasource` | Required | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. [1] | `datasource`; `http`; `pubsub` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`faas.coldstart`](/docs/attributes-registry/faas.md) | boolean | A boolean that is true if the serverless function is executed for the first time (aka cold-start). | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** For the server/consumer span on the incoming side, `faas.trigger` MUST be set. @@ -134,6 +134,16 @@ the event type. If clients set it, it should be the same as the trigger that corresponding incoming would have (i.e., this has nothing to do with the underlying transport used to make the API call to invoke the lambda, which is often HTTP). + +`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http` | To provide an answer to an inbound HTTP request | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `timer` | A function is scheduled to be executed regularly | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other` | If none of the others apply | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ### Resource attributes as incoming FaaS span attributes @@ -158,12 +168,12 @@ The values reported by the client for the attributes listed below SHOULD be equa the corresponding [FaaS resource attributes][] and [Cloud resource attributes][], which the invoked FaaS instance reports about itself, if it's instrumented. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `faas.invoked_name` | string | The name of the invoked function. [1] | `my-function` | Required | -| `faas.invoked_provider` | string | The cloud provider of the invoked function. [2] | `alibaba_cloud` | Required | -| `faas.invoked_region` | string | The cloud region of the invoked function. [3] | `eu-central-1` | Conditionally Required: [4] | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`faas.invoked_name`](/docs/attributes-registry/faas.md) | string | The name of the invoked function. [1] | `my-function` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`faas.invoked_provider`](/docs/attributes-registry/faas.md) | string | The cloud provider of the invoked function. [2] | `alibaba_cloud`; `aws`; `azure` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`faas.invoked_region`](/docs/attributes-registry/faas.md) | string | The cloud region of the invoked function. [3] | `eu-central-1` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function. @@ -173,15 +183,15 @@ which the invoked FaaS instance reports about itself, if it's instrumented. **[4]:** For some cloud providers, like AWS or GCP, the region in which a function is hosted is essential to uniquely identify the function and also part of its endpoint. Since it's part of the endpoint being called, the region is always known to clients. In these cases, `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional. -`faas.invoked_provider` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +`faas.invoked_provider` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Value | Description | -|---|---| -| `alibaba_cloud` | Alibaba Cloud | -| `aws` | Amazon Web Services | -| `azure` | Microsoft Azure | -| `gcp` | Google Cloud Platform | -| `tencent_cloud` | Tencent Cloud | +| Value | Description | Stability | +|---|---|---| +| `alibaba_cloud` | Alibaba Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws` | Amazon Web Services | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure` | Microsoft Azure | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp` | Google Cloud Platform | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tencent_cloud` | Tencent Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | [FaaS resource attributes]: ../resource/faas.md @@ -196,21 +206,21 @@ This section describes how to handle the span creation and additional attributes A datasource function is triggered as a response to some data source operation such as a database or filesystem read/write. FaaS instrumentations that produce `faas` spans with trigger `datasource`, SHOULD use the following set of attributes. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `faas.document.collection` | string | The name of the source on which the triggering operation was performed. For example, in Cloud Storage or S3 corresponds to the bucket name, and in Cosmos DB to the database name. | `myBucketName`; `myDbName` | Required | -| `faas.document.operation` | string | Describes the type of the operation that was performed on the data. | `insert` | Required | -| `faas.document.time` | string | A string containing the time when the data was accessed in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Recommended | -| `faas.document.name` | string | The document name/table subjected to the operation. For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table name. | `myFile.txt`; `myTableName` | Recommended | - -`faas.document.operation` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. - -| Value | Description | -|---|---| -| `insert` | When a new object is created. | -| `edit` | When an object is modified. | -| `delete` | When an object is deleted. | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`faas.document.collection`](/docs/attributes-registry/faas.md) | string | The name of the source on which the triggering operation was performed. For example, in Cloud Storage or S3 corresponds to the bucket name, and in Cosmos DB to the database name. | `myBucketName`; `myDbName` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`faas.document.operation`](/docs/attributes-registry/faas.md) | string | Describes the type of the operation that was performed on the data. | `insert`; `edit`; `delete` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`faas.document.name`](/docs/attributes-registry/faas.md) | string | The document name/table subjected to the operation. For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table name. | `myFile.txt`; `myTableName` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`faas.document.time`](/docs/attributes-registry/faas.md) | string | A string containing the time when the data was accessed in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`faas.document.operation` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `insert` | When a new object is created. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `edit` | When an object is modified. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `delete` | When an object is deleted. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ### HTTP @@ -230,10 +240,10 @@ This way, it is possible to correlate each individual message with its invocatio A function is scheduled to be executed regularly. The following additional attributes are recommended. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `faas.time` | string | A string containing the function invocation time in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Recommended | -| `faas.cron` | string | A string containing the schedule period as [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). | `0/5 * * * ? *` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`faas.cron`](/docs/attributes-registry/faas.md) | string | A string containing the schedule period as [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). | `0/5 * * * ? *` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`faas.time`](/docs/attributes-registry/faas.md) | string | A string containing the function invocation time in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ### Other @@ -261,4 +271,4 @@ This example shows the FaaS attributes for a (non-FaaS) process hosted on Google | Resource | `faas.instance` | n/a | `"my-lambda-function:instance-0001"` | | Resource | `cloud.resource_id` | n/a | `"arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function"` | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/feature-flags/README.md b/docs/feature-flags/README.md index 30a308837a..38acc00d52 100644 --- a/docs/feature-flags/README.md +++ b/docs/feature-flags/README.md @@ -1,7 +1,7 @@ @@ -17,4 +17,4 @@ Semantic conventions for feature flags are defined for the following signals: * [Feature Flags in Spans](feature-flags-spans.md): Semantic Conventions for recording feature flags in *spans*. * [Feature Flags in Logs](feature-flags-logs.md): Semantic Conventions for recording feature flags in *logs*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 8f19707e75..f6644e8053 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -7,8 +7,8 @@ linkTitle: Logs **Status**: [Experimental][DocumentStatus] This document defines semantic conventions for recording feature flag evaluations as -a [log record](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/data-model.md#log-and-event-record-definition) emitted through the -[Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/bridge-api.md#emit-a-logrecord). +a [log record](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/logs/data-model.md#log-and-event-record-definition) emitted through the +[Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/logs/bridge-api.md#emit-a-logrecord). This is useful when a flag is evaluated outside of a transaction context such as when the application loads or on a timer. To record a flag evaluation as a part of a transaction context, @@ -28,23 +28,23 @@ section of the trace semantic convention for feature flag evaluations. ## Recording an Evaluation Feature flag evaluations SHOULD be recorded as attributes on the -[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/bridge-api.md#logger) emit +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/logs/bridge-api.md#logger) emit operations. Evaluations MAY be recorded on "logs" or "events" depending on the context. ## Attributes The table below indicates which attributes should be added to the -[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. -The event name MUST be `feature_flag`. +The event name MUST be `feature_flag` -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`feature_flag.key`](feature-flags-spans.md) | string | The unique identifier of the feature flag. | `logo-color` | Required | -| [`feature_flag.provider_name`](feature-flags-spans.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | Recommended | -| [`feature_flag.variant`](feature-flags-spans.md) | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The unique identifier of the feature flag. | `logo-color` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.provider_name`](/docs/attributes-registry/feature-flag.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** A semantic identifier, commonly referred to as a variant, provides a means for referring to a value without including the value itself. This can @@ -56,4 +56,4 @@ semantic identifier is unavailable. String representation of the value should be determined by the implementer. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/feature-flags/feature-flags-spans.md b/docs/feature-flags/feature-flags-spans.md index 0bf5de6174..71a3f9684e 100644 --- a/docs/feature-flags/feature-flags-spans.md +++ b/docs/feature-flags/feature-flags-spans.md @@ -42,13 +42,13 @@ It's intended to be vendor neutral and provide flexibility for current and futur A flag evaluation SHOULD be recorded as an Event on the span during which it occurred. -The event name MUST be `feature_flag`. +The event name MUST be `feature_flag` -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `feature_flag.key` | string | The unique identifier of the feature flag. | `logo-color` | Required | -| `feature_flag.provider_name` | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | Recommended | -| `feature_flag.variant` | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The unique identifier of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.provider_name`](/docs/attributes-registry/feature-flag.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** A semantic identifier, commonly referred to as a variant, provides a means for referring to a value without including the value itself. This can @@ -60,4 +60,4 @@ semantic identifier is unavailable. String representation of the value should be determined by the implementer. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/gen-ai/README.md b/docs/gen-ai/README.md new file mode 100644 index 0000000000..1197a88522 --- /dev/null +++ b/docs/gen-ai/README.md @@ -0,0 +1,25 @@ + + +# Semantic Conventions for Generative AI systems + +**Status**: [Experimental][DocumentStatus] + +**Warning**: +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 LLM operations are defined for the following signals: + +* [LLM Spans](llm-spans.md): Semantic Conventions for LLM requests - *spans*. + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/gen-ai/llm-spans.md b/docs/gen-ai/llm-spans.md new file mode 100644 index 0000000000..5cf34e5ffd --- /dev/null +++ b/docs/gen-ai/llm-spans.md @@ -0,0 +1,90 @@ + + +# 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 name of the LLM foundation model vendor. [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` | `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` | `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 | +|---|---|---| +| `openai` | OpenAI | ![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://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/general/README.md b/docs/general/README.md index ec1e248fda..a4bff5597e 100644 --- a/docs/general/README.md +++ b/docs/general/README.md @@ -1,7 +1,7 @@ diff --git a/docs/general/attribute-naming.md b/docs/general/attribute-naming.md new file mode 100644 index 0000000000..57a99b62cd --- /dev/null +++ b/docs/general/attribute-naming.md @@ -0,0 +1,160 @@ +# Attribute Naming + +**Status**: [Stable][DocumentStatus] + +
+Table of Contents + + + +- [Name Pluralization guidelines](#name-pluralization-guidelines) +- [Name Reuse Prohibition](#name-reuse-prohibition) +- [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors) +- [Recommendations for Application Developers](#recommendations-for-application-developers) +- [otel.\* Namespace](#otel-namespace) + + + +
+ +_This section applies to Resource, Span, Log, and Metric attribute names (also +known as the "attribute keys"). For brevity within this section when we use the +term "name" without an adjective it is implied to mean "attribute name"._ + +Every name MUST be a valid Unicode sequence. + +_Note: we merely require that the names are represented as Unicode sequences. +This specification does not define how exactly the Unicode sequences are +encoded. The encoding can vary from one programming language to another and from +one wire format to another. Use the idiomatic way to represent Unicode in the +particular programming language or wire format._ + +Names SHOULD follow these rules: + +- Names SHOULD be lowercase. + +- Use namespacing to avoid name clashes. Delimit the namespaces using a dot + character. For example `service.version` denotes the service version where + `service` is the namespace and `version` is an attribute in that namespace. + +- Namespaces can be nested. For example `telemetry.sdk` is a namespace inside + top-level `telemetry` namespace and `telemetry.sdk.name` is an attribute + inside `telemetry.sdk` namespace. Note: the fact that an entity is located + within another entity is typically not a sufficient reason for forming nested + namespaces. The purpose of a namespace is to avoid name clashes, not to + indicate entity hierarchies. This purpose should primarily drive the decision + about forming nested namespaces. + +- For each multi-word dot-delimited component of the attribute name separate the + words by underscores (i.e. use snake_case). For example + `http.response.status_code` denotes the status code in the http namespace. + +- Names SHOULD NOT coincide with namespaces. For example if + `service.instance.id` is an attribute name then it is no longer valid to have + an attribute named `service.instance` because `service.instance` is already a + namespace. Because of this rule be careful when choosing names: every existing + name prohibits existence of an equally named namespace in the future, and vice + versa: any existing namespace prohibits existence of an equally named + attribute key in the future. + +## Name Pluralization guidelines + +- When an attribute represents a single entity, the attribute name SHOULD be + singular. Examples: `host.name`, `container.id`. + +- When attribute can represent multiple entities, the attribute name SHOULD be + pluralized and the value type SHOULD be an array. E.g. `process.command_args` + might include multiple values: the executable name and command arguments. + +- When an attribute represents a measurement, + [Metric Name Pluralization Guidelines](./metrics.md#pluralization) SHOULD be + followed for the attribute name. + +## Name Reuse Prohibition + +A new attribute MUST NOT be added with the same name as an attribute that +existed in the past but was renamed (with a corresponding schema file). + +When introducing a new attribute name check all existing schema files to make +sure the name does not appear as a key of any "rename_attributes" section (keys +denote old attribute names in rename operations). + +## Recommendations for OpenTelemetry Authors + +- All names that are part of OpenTelemetry semantic conventions SHOULD be part + of a namespace. + +- When coming up with a new semantic convention make sure to check existing + namespaces ([Semantic Conventions](./README.md)) to see if the new name fits. + +- When a new namespace is necessary consider whether it should be a top-level + namespace (e.g. `service`) or a nested namespace (e.g. `service.instance`). + +- Semantic conventions exist for four areas: for Resource, Span, Log, and Metric + attribute names. In addition, for spans we have two more areas: Event and Link + attribute names. Identical namespaces or names in all these areas MUST have + identical meanings. For example the `http.request.method` span attribute name + denotes exactly the same concept as the `http.request.method` metric + attribute, has the same data type and the same set of possible values (in both + cases it records the value of the HTTP protocol's request method as a string). + +- Semantic conventions MUST limit names to printable Basic Latin characters + (more precisely to + [U+0021 .. U+007E]() + subset of Unicode code points). It is recommended to further limit names to + the following Unicode code points: Latin alphabet, Numeric, Underscore, Dot + (as namespace delimiter). + +## Recommendations for Application Developers + +As an application developer when you need to record an attribute first consult +existing [semantic conventions](./README.md). If an appropriate name does not +exists you will need to come up with a new name. To do that consider a few +options: + +- The name is specific to your company and may be possibly used outside the + company as well. To avoid clashes with names introduced by other companies (in + a distributed system that uses applications from multiple vendors) it is + recommended to prefix the new name by your company's reverse domain name, e.g. + `com.acme.shopname`. + +- The name is specific to your application that will be used internally only. If + you already have an internal company process that helps you to ensure no name + clashes happen then feel free to follow it. Otherwise it is recommended to + prefix the attribute name by your application name, provided that the + application name is reasonably unique within your organization (e.g. + `myuniquemapapp.longitude` is likely fine). Make sure the application name + does not clash with an existing semantic convention namespace. + +- It is not recommended to use existing OpenTelemetry semantic convention + namespace as a prefix for a new company- or application-specific attribute + name. Doing so may result in a name clash in the future, if OpenTelemetry + decides to use that same name for a different purpose or if some other third + party instrumentation decides to use that exact same attribute name and you + combine that instrumentation with your own. + +- The name may be generally applicable to applications in the industry. In that + case consider submitting a proposal to this specification to add a new name to + the semantic conventions, and if necessary also to add a new namespace. + +It is recommended to limit names to printable Basic Latin characters (more +precisely to +[U+0021 .. U+007E]() +subset of Unicode code points). + +## otel.\* Namespace + +Attribute names that start with `otel.` are reserved to be defined by +OpenTelemetry specification. These are typically used to express OpenTelemetry +concepts in formats that don't have a corresponding concept. + +For example, the `otel.scope.name` attribute is used to record the +instrumentation scope name, which is an OpenTelemetry concept that is natively +represented in OTLP, but does not have an equivalent in other telemetry formats +and protocols. + +Any additions to the `otel.*` namespace MUST be approved as part of +OpenTelemetry specification. + +[DocumentStatus]: + https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/general/attribute-requirement-level.md b/docs/general/attribute-requirement-level.md new file mode 100644 index 0000000000..d16d073372 --- /dev/null +++ b/docs/general/attribute-requirement-level.md @@ -0,0 +1,127 @@ +# Attribute Requirement Levels + +**Status**: [Stable][DocumentStatus] + +
+Table of Contents + + + +- [Required](#required) +- [Conditionally Required](#conditionally-required) +- [Recommended](#recommended) +- [Opt-In](#opt-in) +- [Performance suggestions](#performance-suggestions) + + + +
+ +_This section applies to Log, Metric, Resource, and Span, and describes +requirement levels for attributes defined in semantic conventions._ + +Attribute requirement levels apply to the +[instrumentation library](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/glossary.md#instrumentation-library). + +The following attribute requirement levels are specified: + +- [Required](#required) +- [Conditionally Required](#conditionally-required) +- [Recommended](#recommended) +- [Opt-In](#opt-in) + +The requirement level for an attribute is specified by semantic conventions +depending on attribute availability across instrumented entities, performance, +security, and other factors. When specifying requirement levels, a semantic +convention MUST take into account signal-specific requirements. + +For example, Metric attributes that may have high cardinality can only be +defined with `Opt-In` level. + +A semantic convention that refers to an attribute from another semantic +convention MAY modify the requirement level within its own scope. Otherwise, +requirement level from the referred semantic convention applies. + + + +For example, [Database semantic convention](../database/README.md) references +`network.transport` attribute defined in [General attributes](./README.md) with +`Conditionally Required` level on it. + +## Required + +All instrumentations MUST populate the attribute. A semantic convention defining +a Required attribute expects an absolute majority of instrumentation libraries +and applications are able to efficiently retrieve and populate it, and can +additionally meet requirements for cardinality, security, and any others +specific to the signal defined by the convention. `http.request.method` is an +example of a Required attribute. + +_Note: Consumers of telemetry can detect if a telemetry item follows a specific +semantic convention by checking for the presence of a `Required` attribute +defined by such convention. For example, the presence of the `db.system` +attribute on a span can be used as an indication that the span follows database +semantics._ + +## Conditionally Required + +All instrumentations MUST populate the attribute when the given condition is +satisfied. The semantic convention of a `Conditionally Required` attribute MUST +clarify the condition under which the attribute is to be populated. + +`http.route` is an example of a conditionally required attribute that is +populated when the instrumented HTTP framework provides route information for +the instrumented request. Some low-level HTTP server implementations do not +support routing and corresponding instrumentations can't populate the attribute. + +When a `Conditionally Required` attribute's condition is not satisfied, and +there is no requirement to populate the attribute, semantic conventions MAY +provide special instructions on how to handle it. If no instructions are given +and if instrumentation can populate the attribute, instrumentation SHOULD use +the `Opt-In` requirement level on the attribute. + + + +For example, `server.address` is `Conditionally Required` by the +[Database convention](../database/README.md) when available. When +`network.peer.address` is available instead, instrumentation can do a DNS +lookup, cache and populate `server.address`, but only if the user explicitly +enables the instrumentation to do so, considering the performance issues that +DNS lookups introduce. + +## Recommended + +Instrumentations SHOULD add the attribute by default if it's readily available +and can be [efficiently populated](#performance-suggestions). Instrumentations +MAY offer a configuration option to disable Recommended attributes. + +Instrumentations that decide not to populate `Recommended` attributes due to +[performance](#performance-suggestions), security, privacy, or other +consideration by default, SHOULD allow for users to opt-in to emit them as +defined for the `Opt-In` requirement level (if the attributes are logically +applicable). + +## Opt-In + +Instrumentations SHOULD populate the attribute if and only if the user +configures the instrumentation to do so. Instrumentation that doesn't support +configuration MUST NOT populate `Opt-In` attributes. + +This attribute requirement level is recommended for attributes that are +particularly expensive to retrieve or might pose a security or privacy risk. +These should therefore only be enabled explicitly by a user making an informed +decision. + +## Performance suggestions + +Here are several examples of expensive operations to be avoided by default: + +- DNS lookups to populate `server.address` when only an IP address is available + to the instrumentation. Caching lookup results does not solve the issue for + all possible cases and should be avoided by default too. +- forcing an `http.route` calculation before the HTTP framework calculates it +- reading response stream to find `http.response.body.size` when + `Content-Length` header is not available + +[DocumentStatus]: + https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/general/attributes.md b/docs/general/attributes.md index 13e98d5595..c779547551 100644 --- a/docs/general/attributes.md +++ b/docs/general/attributes.md @@ -15,17 +15,21 @@ Particular operations may refer to or require some of these attributes. -- [Server and client attributes](#server-and-client-attributes) - * [Server attributes](#server-attributes) - + [`server.address`](#serveraddress) - + [`server.socket.*` attributes](#serversocket-attributes) - * [Client attributes](#client-attributes) - + [Connecting through intermediary](#connecting-through-intermediary) -- [Network attributes](#network-attributes) - * [Source and destination attributes](#source-and-destination-attributes) - + [Source](#source) - + [Destination](#destination) - * [Network connection and carrier attributes](#network-connection-and-carrier-attributes) +- [Server, client and shared network attributes](#server-client-and-shared-network-attributes) + - [Address and port attributes](#address-and-port-attributes) + - [Server attributes](#server-attributes) + - [`server.address`](#serveraddress) + - [Client attributes](#client-attributes) + - [Source and destination attributes](#source-and-destination-attributes) + - [Source](#source) + - [Destination](#destination) + - [Other network attributes](#other-network-attributes) + - [`network.peer.*` and `network.local.*` attributes](#networkpeer-and-networklocal-attributes) + - [Client/server examples using `network.peer.*`](#clientserver-examples-using--networkpeer) + - [Simple client/server example](#simple-clientserver-example) + - [Client/server example with reverse proxy](#clientserver-example-with-reverse-proxy) + - [Client/server example with forward proxy](#clientserver-example-with-forward-proxy) + - [Network connection and carrier attributes](#network-connection-and-carrier-attributes) - [General remote service attributes](#general-remote-service-attributes) - [General identity attributes](#general-identity-attributes) - [General thread attributes](#general-thread-attributes) @@ -33,7 +37,10 @@ Particular operations may refer to or require some of these attributes. -## Server and client attributes + + + +## Server, client and shared network attributes These attributes may be used to describe the client and server in a connection-based network interaction where there is one side that initiates the connection (the client is the side that initiates the connection). @@ -45,6 +52,13 @@ This also covers UDP network interactions where one side initiates the interacti In an ideal situation, not accounting for proxies, multiple IP addresses or host names, the `server.*` attributes are the same on the client and server. +### Address and port attributes + +For all IP-based protocols, the "address" should be just the IP-level address. +Protocol-specific parts of an address are split into other attributes (when applicable) such as "port" attributes for +TCP and UDP. If such transport-specific information is collected and the attribute name does not already uniquely +identify the transport, then setting [`network.transport`](#other-network-attributes) is especially encouraged. + ### Server attributes > **Warning** @@ -53,22 +67,19 @@ Once the HTTP semantic conventions are declared stable, changes to the attribute if they do not cause breaking changes to HTTP semantic conventions. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `server.address` | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | Recommended | -| `server.port` | int | Logical server port number | `80`; `8080`; `443` | Recommended | -| `server.socket.domain` | string | The domain name of an immediate peer. [1] | `proxy.example.com` | Recommended: If different than `server.address`. | -| `server.socket.address` | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | -| `server.socket.port` | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | - -**[1]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + +**[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. `server.address` and `server.port` represent logical server name and port. Semantic conventions that refer to these attributes SHOULD specify what these attributes mean in their context. -Semantic conventions and instrumentations that populate both logical (`server.address` and `server.port`) and socket-level (`server.socket.*`) attributes SHOULD set socket-level attributes only when they don't match logical ones. For example, when direct connection to the remote destination is established and `server.address` is populated, `server.socket.domain` SHOULD NOT be set. Check out [Connecting through intermediary](#connecting-through-intermediary) for more information. - #### `server.address` For IP-based communication, the name should be a DNS host name of the service. On client side it matches remote service name, on server side, it represents local service name as seen externally on clients. @@ -85,28 +96,6 @@ the name should explicitly be set to the empty string to distinguish it from the For Unix domain socket, `server.address` attribute represents remote endpoint address on the client side and local endpoint address on the server side. -#### `server.socket.*` attributes - -_Note: this section applies to socket connections visible to instrumentations. Instrumentations have limited knowledge about intermediaries communications goes through such as [transparent proxies](https://www.rfc-editor.org/rfc/rfc3040.html#section-2.5) or VPN servers. Higher-level instrumentations such as HTTP don't always have access to the socket-level information and may not be able to populate socket-level attributes._ - -Socket-level attributes identify peer and host that are directly connected to each other. Since instrumentations may have limited knowledge on network information, instrumentations SHOULD populate such attributes to the best of their knowledge when populate them at all. - -_Note: Specific structures and methods to obtain socket-level attributes are mentioned here only as examples. Instrumentations would usually use Socket API provided by their environment or sockets implementations._ - -For IP-based communication, `server.socket.domain` represents either fully qualified domain name of immediate peer and `server.socket.address` to the IP address (or one specific to network family). - -`server.socket.domain`, `server.socket.address`, and `server.socket.port` describe server side of socket communication. For example, when connecting using `connect(2)` -on [Linux](https://man7.org/linux/man-pages/man2/connect.2.html) or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-connect) -with `AF_INET` address family, they represent `sin_addr` and `sin_port` fields of [`sockaddr_in`](https://man7.org/linux/man-pages/man7/ip.7.html) structure. - -On client side, address and port can be obtained by calling `getpeername` method on [Linux](https://man7.org/linux/man-pages/man2/getpeername.2.html) or -[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getpeername). - -On server side address and port can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.html) or -[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname). - -`server.socket.port` SHOULD only be populated for families that have notion of port. - ### Client attributes > **Warning** @@ -115,165 +104,185 @@ Once the HTTP semantic conventions are declared stable, changes to the attribute if they do not cause breaking changes to HTTP semantic conventions. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `client.address` | string | Client address - unix domain socket name, IPv4 or IPv6 address. [1] | `/tmp/my.sock`; `10.1.2.80` | Recommended | -| `client.port` | int | Client port number [2] | `65123` | Recommended | -| `client.socket.address` | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | -| `client.socket.port` | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`client.address`](/docs/attributes-registry/client.md) | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`client.port`](/docs/attributes-registry/client.md) | int | Client port number. [2] | `65123` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent client address behind any intermediaries (e.g. proxies) if it's available. +**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. -**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent client port behind any intermediaries (e.g. proxies) if it's available. +**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. -`client.socket.address` and `client.socket.port` represent physical client name and port. - -For IP-based communication, the `client.socket.address` should be a IP address, Unix domain name, or another address specific to network type. +### Source and destination attributes -On server side, `client.socket.address` identifies the direct peer endpoint socket address. For example, when using `bind(2)` -on [Linux](https://man7.org/linux/man-pages/man2/bind.2.html) or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-bind) -with `AF_INET` address family, represent `sin_addr` and `sin_port` fields of `sockaddr_in` structure. +These attributes may be used to describe the sender and receiver of a network exchange/packet. These should be used +when there is no client/server relationship between the two sides, or when that relationship is unknown. +This covers low-level network interactions (e.g. packet tracing) where you don't know if +there was a connection or which side initiated it. +This also covers unidirectional UDP flows and peer-to-peer communication where the +"user-facing" surface of the protocol / API does not expose a clear notion of client and server. -On client side it represents local socket address and port can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.html), -[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname). +#### Source -#### Connecting through intermediary + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`source.address`](/docs/attributes-registry/source.md) | string | Source address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `source.example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`source.port`](/docs/attributes-registry/source.md) | int | Source port number | `3389`; `2888` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -When connecting to the remote destination through an intermediary (e.g. proxy), client instrumentations SHOULD set `server.address` and `server.port` to logical remote destination address and `server.socket.name`, `server.socket.address` and `server.socket.port` to the socket peer connection is established with - the intermediary. +**[1]:** When observed from the destination side, and when communicating through an intermediary, `source.address` SHOULD represent the source address behind any intermediaries, for example proxies, if it's available. + -`server.socket.domain` SHOULD be set to the DNS name used to resolve `server.socket.address` if it's readily available. Instrumentations -SHOULD NOT do DNS lookups to obtain `server.socket.address`. If peer information available to instrumentation -can represent DNS name or IP address, instrumentation SHOULD NOT attempt to parse it and SHOULD only set `server.socket.domain`. +#### Destination -_Note: Telemetry consumers can obtain IP address from telemetry item by first checking `server.socket.address` and if not present, falling back to `server.socket.domain`._ +Destination fields capture details about the receiver of a network exchange/packet. -For example, [URL Host component](https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2) can contain IP address or DNS name and -instrumentations that don't have access to socket-level communication can only populate `server.socket.domain`. -Instrumentations that have access to socket connection, may be able to populate valid `server.socket.address` instead of or -in addition to DNS name. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`destination.address`](/docs/attributes-registry/destination.md) | string | Destination address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `destination.example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`destination.port`](/docs/attributes-registry/destination.md) | int | Destination port number | `3389`; `2888` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -Server instrumentations that leverage `client.address` and `client.port` attributes SHOULD set them to originating client address and port behind all proxies if this information is available. -The `client.socket.address` and `client.socket.port` attributes then SHOULD contain immediate client peer address and port. +**[1]:** When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent the destination address behind any intermediaries, for example proxies, if it's available. + -If only immediate peer information is available, it should be set on `client.address` and `client.port` and `client.socket.*` attributes SHOULD NOT be set. + -## Network attributes +### Other network attributes > **Warning** > Attributes in this section are in use by the HTTP semantic conventions. Once the HTTP semantic conventions are declared stable, changes to the attributes in this section will only be allowed if they do not cause breaking changes to HTTP semantic conventions. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `network.transport` | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | -| `network.type` | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| `network.protocol.name` | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| `network.protocol.version` | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`network.local.address`](/docs/attributes-registry/network.md) | string | Local address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.local.port`](/docs/attributes-registry/network.md) | int | Local port number of the network connection. | `65123` | `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. | `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) | +| [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `amqp`; `http`; `mqtt` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [2] | `1.1`; `2` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.type`](/docs/attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[1]:** The value SHOULD be normalized to lowercase. -`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +**[2]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -| Value | Description | -|---|---| -| `tcp` | TCP | -| `udp` | UDP | -| `pipe` | Named or anonymous pipe. See note below. | -| `unix` | Unix domain socket | +**[3]:** The value SHOULD be normalized to lowercase. -`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. -| Value | Description | -|---|---| -| `ipv4` | IPv4 | -| `ipv6` | IPv6 | - +**[4]:** The value SHOULD be normalized to lowercase. -### Source and destination attributes +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -These attributes may be used to describe the sender and receiver of a network exchange/packet. These should be used -when there is no client/server relationship between the two sides, or when that relationship is unknown. -This covers low-level network interactions (e.g. packet tracing) where you don't know if -there was a connection or which side initiated it. -This also covers unidirectional UDP flows and peer-to-peer communication where the -"user-facing" surface of the protocol / API does not expose a clear notion of client and server. +| Value | Description | Stability | +|---|---|---| +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -#### Source - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `source.domain` | string | The domain name of the source system. [1] | `foo.example.com` | Recommended | -| `source.address` | string | Source address, for example IP address or Unix socket name. | `10.5.3.2` | Recommended | -| `source.port` | int | Source port number | `3389`; `2888` | Recommended | +`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -**[1]:** This value may be a host name, a fully qualified domain name, or another host naming format. +| Value | Description | Stability | +|---|---|---| +| `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -#### Destination +#### `network.peer.*` and `network.local.*` attributes -Destination fields capture details about the receiver of a network exchange/packet. +These attributes identify network peers that are directly connected to each other. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `destination.domain` | string | The domain name of the destination system. [1] | `foo.example.com` | Recommended | -| `destination.address` | string | Peer address, for example IP address or UNIX socket name. | `10.5.3.2` | Recommended | -| `destination.port` | int | Peer port number | `3389`; `2888` | Recommended | +`network.peer.address` and `network.local.address` should be IP addresses, Unix domain socket names, or other addresses specific to network type. -**[1]:** This value may be a host name, a fully qualified domain name, or another host naming format. - +_Note: Specific structures and methods to obtain socket-level attributes are mentioned here only as examples. Instrumentations would usually use Socket API provided by their environment or sockets implementations._ -### Network connection and carrier attributes - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `network.connection.type` | string | The internet connection type. | `wifi` | Recommended | -| `network.connection.subtype` | string | This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. | `LTE` | Recommended | -| `network.carrier.name` | string | The name of the mobile carrier. | `sprint` | Recommended | -| `network.carrier.mcc` | string | The mobile carrier country code. | `310` | Recommended | -| `network.carrier.mnc` | string | The mobile carrier network code. | `001` | Recommended | -| `network.carrier.icc` | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` | Recommended | - -`network.connection.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. - -| Value | Description | -|---|---| -| `wifi` | wifi | -| `wired` | wired | -| `cell` | cell | -| `unavailable` | unavailable | -| `unknown` | unknown | - -`network.connection.subtype` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. - -| Value | Description | -|---|---| -| `gprs` | GPRS | -| `edge` | EDGE | -| `umts` | UMTS | -| `cdma` | CDMA | -| `evdo_0` | EVDO Rel. 0 | -| `evdo_a` | EVDO Rev. A | -| `cdma2000_1xrtt` | CDMA2000 1XRTT | -| `hsdpa` | HSDPA | -| `hsupa` | HSUPA | -| `hspa` | HSPA | -| `iden` | IDEN | -| `evdo_b` | EVDO Rev. B | -| `lte` | LTE | -| `ehrpd` | EHRPD | -| `hspap` | HSPAP | -| `gsm` | GSM | -| `td_scdma` | TD-SCDMA | -| `iwlan` | IWLAN | -| `nr` | 5G NR (New Radio) | -| `nrnsa` | 5G NRNSA (New Radio Non-Standalone) | -| `lte_ca` | LTE CA | +When connecting using `connect(2)` ([Linux or other POSIX systems](https://man7.org/linux/man-pages/man2/connect.2.html) / +[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-connect)) +or `bind(2)`([Linux or other POSIX systems](https://man7.org/linux/man-pages/man2/bind.2.html) / +[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-bind)) +with `AF_INET` address family, `network.peer.address` and `network.peer.port` represent `sin_addr` and `sin_port` fields +of `sockaddr_in` structure. + +`network.peer.address` and `network.peer.port` can be obtained by calling `getpeername` method +([Linux or other POSIX systems](https://man7.org/linux/man-pages/man2/getpeername.2.html) / +[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getpeername)). + +`network.local.address` and `network.local.port` can be obtained by calling `getsockname` method +([Linux or other POSIX systems](https://man7.org/linux/man-pages/man2/getsockname.2.html) / +[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname)). + +##### Client/server examples using `network.peer.*` + +Note that `network.local.*` attributes are not included in these examples since they are typically Opt-In. + +###### Simple client/server example + +![simple.png](simple.png) + +###### Client/server example with reverse proxy + +![reverse-proxy.png](reverse-proxy.png) + +###### Client/server example with forward proxy + +![forward-proxy.png](forward-proxy.png) + +#### Network connection and carrier attributes + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`network.carrier.icc`](/docs/attributes-registry/network.md) | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`network.carrier.mcc`](/docs/attributes-registry/network.md) | string | The mobile carrier country code. | `310` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`network.carrier.mnc`](/docs/attributes-registry/network.md) | string | The mobile carrier network code. | `001` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`network.carrier.name`](/docs/attributes-registry/network.md) | string | The name of the mobile carrier. | `sprint` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`network.connection.subtype`](/docs/attributes-registry/network.md) | string | This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. | `LTE` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`network.connection.type`](/docs/attributes-registry/network.md) | string | The internet connection type. | `wifi` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`network.connection.subtype` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `gprs` | GPRS | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `edge` | EDGE | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `umts` | UMTS | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cdma` | CDMA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `evdo_0` | EVDO Rel. 0 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `evdo_a` | EVDO Rev. A | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cdma2000_1xrtt` | CDMA2000 1XRTT | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hsdpa` | HSDPA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hsupa` | HSUPA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hspa` | HSPA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iden` | IDEN | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `evdo_b` | EVDO Rev. B | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `lte` | LTE | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ehrpd` | EHRPD | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hspap` | HSPAP | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gsm` | GSM | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `td_scdma` | TD-SCDMA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iwlan` | IWLAN | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nr` | 5G NR (New Radio) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nrnsa` | 5G NRNSA (New Radio Non-Standalone) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `lte_ca` | LTE CA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`network.connection.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `wifi` | wifi | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `wired` | wired | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cell` | cell | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unavailable` | unavailable | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unknown` | unknown | ![Experimental](https://img.shields.io/badge/-experimental-blue) | For `Unix` and `pipe`, since the connection goes over the file system instead of being directly to a known peer, `server.address` is the only attribute that usually makes sense (see description of `server.address` below). @@ -285,9 +294,9 @@ Users can define what the name of a service is based on their particular semanti Instrumentations SHOULD provide a way for users to configure this name. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `peer.service` | string | The [`service.name`](/docs/resource/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. | `AuthTokenCache` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`peer.service`](/docs/attributes-registry/peer.md) | string | The [`service.name`](/docs/resource/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. | `AuthTokenCache` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | Examples of `peer.service` that users may specify: @@ -300,11 +309,11 @@ Examples of `peer.service` that users may specify: These attributes may be used for any operation with an authenticated and/or authorized enduser. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `enduser.id` | string | Username or client_id extracted from the access token or [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) header in the inbound request from outside the system. | `username` | Recommended | -| `enduser.role` | string | Actual/assumed role the client is making the request under extracted from token or application security context. | `admin` | Recommended | -| `enduser.scope` | string | Scopes or granted authorities the client currently possesses extracted from token or application security context. The value would come from the scope associated with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3) or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). | `read:message, write:files` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`enduser.id`](/docs/attributes-registry/enduser.md) | string | Username or client_id extracted from the access token or [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) header in the inbound request from outside the system. | `username` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`enduser.role`](/docs/attributes-registry/enduser.md) | string | Actual/assumed role the client is making the request under extracted from token or application security context. | `admin` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`enduser.scope`](/docs/attributes-registry/enduser.md) | string | Scopes or granted authorities the client currently possesses extracted from token or application security context. The value would come from the scope associated with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3) or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). | `read:message, write:files` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | These attributes describe the authenticated user driving the user agent making requests to the instrumented @@ -335,7 +344,7 @@ Examples of where the `enduser.id` value is extracted from: [OpenID Connect 1.0 IDToken]: https://openid.net/specs/openid-connect-core-1_0.html#IDToken [Kerberos]: https://tools.ietf.org/html/rfc4120 [JavaEE/JakartaEE Servlet]: https://jakarta.ee/specifications/platform/8/apidocs/javax/servlet/http/HttpServletRequest.html -[Windows Communication Foundation]: https://docs.microsoft.com/en-us/dotnet/api/system.servicemodel.servicesecuritycontext?view=netframework-4.8 +[Windows Communication Foundation]: https://docs.microsoft.com/dotnet/api/system.servicemodel.servicesecuritycontext?view=netframework-4.8 Given the sensitive nature of this information, SDKs and exporters SHOULD drop these attributes by default and then provide a configuration parameter to turn on retention for use cases where the @@ -347,22 +356,22 @@ These attributes may be used for any operation to store information about a thread that started a span. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `thread.id` | int | Current "managed" thread ID (as opposed to OS thread ID). | `42` | Recommended | -| `thread.name` | string | Current thread name. | `main` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`thread.id`](/docs/attributes-registry/thread.md) | int | Current "managed" thread ID (as opposed to OS thread ID). | `42` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`thread.name`](/docs/attributes-registry/thread.md) | string | Current thread name. | `main` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | Examples of where `thread.id` and `thread.name` can be extracted from: -| Language or platform | `thread.id` | `thread.name` | -|-----------------------|----------------------------------------|------------------------------------| -| JVM | `Thread.currentThread().getId()` | `Thread.currentThread().getName()` | -| .NET | `Thread.CurrentThread.ManagedThreadId` | `Thread.CurrentThread.Name` | -| Python | `threading.current_thread().ident` | `threading.current_thread().name` | -| Ruby | `Thread.current.object_id` | `Thread.current.name` | -| C++ | `std::this_thread::get_id()` | | -| Erlang | `erlang:system_info(scheduler_id)` | | +| Language or platform | `thread.id` | `thread.name` | +|-----------------------|----------------------------------------|------------------------------------------------| +| JVM | `Thread.currentThread().getId()` | `Thread.currentThread().getName()` | +| .NET | `Thread.CurrentThread.ManagedThreadId` | `Thread.CurrentThread.Name` | +| Python | `threading.current_thread().ident` | `threading.current_thread().name` | +| Ruby | `Thread.current.object_id` | `Thread.current.name` | +| C++ | `std::this_thread::get_id()` | | +| Erlang | `erlang:self()` | `erlang:process_info(self(), registered_name)` | ## Source Code Attributes @@ -373,13 +382,14 @@ The attributes listed below allow to report this unit of code and therefore to p about the span. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `code.function` | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` | Recommended | -| `code.namespace` | string | The "namespace" within which `code.function` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. | `com.example.MyHttpService` | Recommended | -| `code.filepath` | string | The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). | `/usr/local/MyApplication/content_root/app/index.php` | Recommended | -| `code.lineno` | int | The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `42` | Recommended | -| `code.column` | int | The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `16` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`code.column`](/docs/attributes-registry/code.md) | int | The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `16` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`code.filepath`](/docs/attributes-registry/code.md) | string | The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). | `/usr/local/MyApplication/content_root/app/index.php` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`code.function`](/docs/attributes-registry/code.md) | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`code.lineno`](/docs/attributes-registry/code.md) | int | The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `42` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`code.namespace`](/docs/attributes-registry/code.md) | string | The "namespace" within which `code.function` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. | `com.example.MyHttpService` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`code.stacktrace`](/docs/attributes-registry/code.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/general/events.md b/docs/general/events.md index bb05d9a015..d9c062a6a1 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -3,13 +3,35 @@ linkTitle: Events aliases: [docs/specs/semconv/general/events-general] ---> -# Semantic Conventions for Event Attributes +# Semantic Conventions for Events **Status**: [Experimental][DocumentStatus] -This document describes the attributes of standalone Events that are represented +This document describes the characteristics of standalone Events that are represented in the data model by `LogRecord`s. +Semantically, an Event is a named occurrence at an instant in time. It signals that +"this thing happened at this time" and provides additional specifics about the occurrence. +Examples of Events might include things like uncaught exceptions, button clicks, user logout, +network connection severed, etc. + +In OpenTelemetry, Events are implemented as a specific type of `LogRecord` that conforms to +the conventions included here, and Events +[have their own API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/event-api.md). +The API abstracts away knowledge of `LogRecord` so that users only deal with Event +semantics. + +In addition to a required name, an Event may contain a _payload_ of any type permitted by the +[LogRecord body](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-body). +In its implementation, the Event _payload_ will constitute the `Body` of the `LogRecord`. +Like all other OpenTelemetry signals, an Event has optional attribute metadata that helps describe +the event context. + +Over time, some Events will be specified by OpenTelemetry and will have documented payload structure, +field semantics, and stability and requirement levels. Other events may be user-defined and carry +bespoke user semantics. When an Event name exists in the semantic conventions, its _payload_ +structure and semantics will also be defined. + The following semantic conventions for events are defined: * **[General](#general-event-attributes): General semantic attributes that may be used in describing Events.** @@ -17,20 +39,10 @@ The following semantic conventions for events are defined: ## General event attributes -Events are recorded as LogRecords that are shaped -in a special way: Event LogRecords have the attributes `event.domain` -and `event.name` (and possibly other LogRecord attributes). - -The `event.domain` attribute is used to logically separate events from different -systems. For example, to record Events from browser apps, mobile apps and -Kubernetes, we could use `browser`, `device` and `k8s` as the domain for their -Events. This provides a clean separation of semantics for events in each of the -domains. - -Within a particular domain, the `event.name` attribute identifies the event. -Events with same domain and name are structurally similar to one another. For -example, some domains could have well-defined schema for their events based on -event names. +Events are recorded as LogRecords that are shaped in a special way: Event +LogRecords MUST have the attribute `event.name` that uniquely identifies the event. +Events with the same `event.name` are structurally similar to one another. Events +may also have other LogRecord attributes. When recording events from an existing system as OpenTelemetry Events, it is possible that the existing system does not have the equivalent of a name or @@ -41,21 +53,11 @@ the event names have low-cardinality, so care must be taken to use fields that identify the class of Events but not the instance of the Event. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `event.name` | string | The name identifies the event. | `click`; `exception` | Required | -| `event.domain` | string | The domain identifies the business context for the events. [1] | `browser` | Required | - -**[1]:** Events across different domains may have same `event.name`, yet be -unrelated events. - -`event.domain` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`event.name`](/docs/attributes-registry/event.md) | string | Identifies the class / type of event. [1] | `browser.mouse.click`; `device.app.lifecycle` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| Value | Description | -|---|---| -| `browser` | Events from browser apps | -| `device` | Events from mobile apps | -| `k8s` | Events from Kubernetes | +**[1]:** Event names are subject to the same rules as [attribute names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/common/attribute-naming.md). Notably, event names are namespaced to avoid collisions and provide a clean separation of semantics for events in separate domains like browser, mobile, and kubernetes. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/general/forward-proxy.png b/docs/general/forward-proxy.png new file mode 100644 index 0000000000..0badc4624c Binary files /dev/null and b/docs/general/forward-proxy.png differ diff --git a/docs/general/logs.md b/docs/general/logs.md index 0ccdbb7c73..e51b5d71f4 100644 --- a/docs/general/logs.md +++ b/docs/general/logs.md @@ -16,8 +16,8 @@ They may be used in any Log Record they apply to. - [General log identification attributes](#general-log-identification-attributes) - [Log Media](#log-media) - * [Log File](#log-file) - * [I/O Stream](#io-stream) + - [Log File](#log-file) + - [I/O Stream](#io-stream) @@ -28,7 +28,7 @@ The following semantic conventions for logs are defined: * [Feature Flags](/docs/feature-flags/feature-flags-logs.md): Semantic attributes that may be used in describing feature flag evaluations in logs. Apart from semantic conventions for logs, [events](events.md), [traces](trace.md), and [metrics](metrics.md), -OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md) with their own +OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). ## General log identification attributes @@ -36,9 +36,9 @@ OpenTelemetry also defines the concept of overarching [Resources](https://github These attributes may be used for identifying a Log Record. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `log.record.uid` | string | A unique identifier for the Log Record. [1] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | Opt-In | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`log.record.uid`](/docs/attributes-registry/log.md) | string | A unique identifier for the Log Record. [1] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values. The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), but other identifiers (e.g. UUID) may be used as needed. @@ -48,7 +48,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.22.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.31.0/specification/resource/sdk.md#resource-sdk) 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. @@ -57,29 +57,29 @@ As such, these should be recorded as Log Record attributes when applicable. They **Description:** A file to which log was emitted. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `log.file.name` | string | The basename of the file. | `audit.log` | Recommended | -| `log.file.path` | string | The full path to the file. | `/var/log/mysql/audit.log` | Opt-In | -| `log.file.name_resolved` | string | The basename of the file, with symlinks resolved. | `uuid.log` | Opt-In | -| `log.file.path_resolved` | string | The full path to the file, with symlinks resolved. | `/var/lib/docker/uuid.log` | Opt-In | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`log.file.name`](/docs/attributes-registry/log.md) | string | The basename of the file. | `audit.log` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`log.file.name_resolved`](/docs/attributes-registry/log.md) | string | The basename of the file, with symlinks resolved. | `uuid.log` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`log.file.path`](/docs/attributes-registry/log.md) | string | The full path to the file. | `/var/log/mysql/audit.log` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`log.file.path_resolved`](/docs/attributes-registry/log.md) | string | The full path to the file, with symlinks resolved. | `/var/lib/docker/uuid.log` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ### I/O Stream **Description:** The I/O stream to which the log was emitted. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `log.iostream` | string | The stream associated with the log. See below for a list of well-known values. | `stdout` | Opt-In | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`log.iostream`](/docs/attributes-registry/log.md) | string | The stream associated with the log. See below for a list of well-known values. | `stdout`; `stderr` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`log.iostream` MUST be one of the following: +`log.iostream` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Value | Description | -|---|---| -| `stdout` | Logs from stdout stream | -| `stderr` | Events from stderr stream | +| Value | Description | Stability | +|---|---|---| +| `stdout` | Logs from stdout stream | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `stderr` | Events from stderr stream | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/general/metric-requirement-level.md b/docs/general/metric-requirement-level.md new file mode 100644 index 0000000000..8372acdbca --- /dev/null +++ b/docs/general/metric-requirement-level.md @@ -0,0 +1,43 @@ +# Metric Requirement Levels + +**Status**: [Stable][DocumentStatus] + +
+Table of Contents + + + +- [Required](#required) +- [Recommended](#recommended) +- [Opt-In](#opt-in) + + + +
+ +The following metric requirement levels are specified: + +- [Required](#required) +- [Recommended](#recommended) +- [Opt-In](#opt-in) + +## Required + +All instrumentations MUST emit the metric. +A semantic convention defining a Required metric expects that an absolute majority of instrumentation libraries and applications are able to efficiently emit it. + +## Recommended + +Instrumentations SHOULD emit the metric by default if it's readily available and can be efficiently emitted. Instrumentations MAY offer a configuration option to disable Recommended metrics. + +Instrumentations that decide not to emit `Recommended` metrics due to performance, security, privacy, or other consideration by default, SHOULD allow for opting in to emitting them as defined for the `Opt-In` requirement level if the metrics are logically applicable. + +## Opt-In + +Instrumentations SHOULD emit the metric if and only if the user configures the instrumentation to do so. +Instrumentation that doesn't support configuration MUST NOT emit `Opt-In` metrics. + +This attribute requirement level is recommended for metrics that are particularly expensive to retrieve or might pose a security or privacy risk. These should therefore only be enabled deliberately by a user making an informed decision. + +[DocumentStatus]: + https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/general/metrics.md b/docs/general/metrics.md index f4b03f34f6..fb96d14606 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -10,15 +10,18 @@ aliases: [docs/specs/semconv/general/metrics-general] - [General Guidelines](#general-guidelines) - * [Name Reuse Prohibition](#name-reuse-prohibition) - * [Units](#units) - * [Pluralization](#pluralization) - + [Use `count` Instead of Pluralization](#use-count-instead-of-pluralization) + - [Name Reuse Prohibition](#name-reuse-prohibition) + - [Metric attributes](#metric-attributes) + - [Units](#units) + - [Naming rules for Counters and UpDownCounters](#naming-rules-for-counters-and-updowncounters) + - [Pluralization](#pluralization) + - [Use `count` Instead of Pluralization for UpDownCounters](#use-count-instead-of-pluralization-for-updowncounters) + - [Do not use `total`](#do-not-use-total) - [General Metric Semantic Conventions](#general-metric-semantic-conventions) - * [Instrument Naming](#instrument-naming) - * [Instrument Units](#instrument-units) - * [Instrument Types](#instrument-types) - * [Consistent UpDownCounter timeseries](#consistent-updowncounter-timeseries) + - [Instrument Naming](#instrument-naming) + - [Instrument Units](#instrument-units) + - [Instrument Types](#instrument-types) + - [Consistent UpDownCounter timeseries](#consistent-updowncounter-timeseries) @@ -26,17 +29,18 @@ The following semantic conventions surrounding metrics are defined: * **[General Guidelines](#general-guidelines): General metrics guidelines.** * [Database](/docs/database/database-metrics.md): For SQL and NoSQL client metrics. -* [FaaS](/docs/faas/faas-metrics.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) metrics. +* [FaaS](/docs/faas/faas-metrics.md): For [Function as a Service](https://wikipedia.org/wiki/Function_as_a_service) metrics. * [HTTP](/docs/http/http-metrics.md): For HTTP client and server metrics. +* [Messaging](/docs/messaging/messaging-metrics.md): For messaging systems (queues, publish/subscribe, etc.) metrics. * [RPC](/docs/rpc/rpc-metrics.md): For RPC client and server metrics. * **System metrics** * [System](/docs/system/system-metrics.md): For standard system metrics. * [Hardware](/docs/system/hardware-metrics.md): For hardware-related metrics. * [Process](/docs/system/process-metrics.md): For standard process metrics. - * [Runtime Environment](/docs/system/runtime-environment-metrics.md): For runtime environment metrics. + * [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics. Apart from semantic conventions for metrics, [traces](trace.md), [logs](logs.md), and [events](events.md), OpenTelemetry also -defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md) with +defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). ## General Guidelines @@ -87,6 +91,26 @@ When introducing a new metric name check all existing schema files to make sure the name does not appear as a key of any "rename_metrics" section (keys denote old metric names in rename operations). +### Metric attributes + +Metric attributes SHOULD follow the general [attribute naming rules](attribute-naming.md). +In particular, metric attributes SHOULD have a namespace. + +Metric attributes SHOULD be added under the metric namespace when their usage and +semantics are exclusive to the metric. + +Examples: + +Attributes `mode` and `mountpoint` for metric `system.filesystem.usage` +should be namespaced as `system.filesystem.mode` and `system.filesystem.mountpoint`. + +Metrics can also have attributes outside of their namespace. + +Examples: + +Metric `http.server.request.duration` uses attributes from the registry such as +`server.port`, `error.type`. + ### Units Conventional metrics or metrics that have their units included in @@ -97,33 +121,43 @@ usable. When building components that interoperate between OpenTelemetry and a system using the OpenMetrics exposition format, use the -[OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/compatibility/prometheus_and_openmetrics.md). +[OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/compatibility/prometheus_and_openmetrics.md). + +### Naming rules for Counters and UpDownCounters + +#### Pluralization -### Pluralization +Metric namespaces SHOULD NOT be pluralized. Metric names SHOULD NOT be pluralized, unless the value being recorded represents discrete instances of a -[countable quantity](https://en.wikipedia.org/wiki/Count_noun). +[countable quantity](https://wikipedia.org/wiki/Count_noun). Generally, the name SHOULD be pluralized only if the unit of the metric in question is a non-unit (like `{fault}` or `{operation}`). Examples: -* `system.filesystem.utilization`, `http.server.duration`, and `system.cpu.time` +* `system.filesystem.utilization`, `http.server.request.duration`, and `system.cpu.time` should not be pluralized, even if many data points are recorded. * `system.paging.faults`, `system.disk.operations`, and `system.network.packets` should be pluralized, even if only a single data point is recorded. -#### Use `count` Instead of Pluralization +#### Use `count` Instead of Pluralization for UpDownCounters If the value being recorded represents the count of concepts signified by the namespace then the metric should be named `count` (within its namespace). -The pluralization rule does not apply in this case. -For example if we have a namespace `system.processes` which contains all metrics related +For example if we have a namespace `system.process` which contains all metrics related to the processes then to represent the count of the processes we can have a metric named -`system.processes.count`. The suffix `count` here indicates that it is the count of -`system.processes`. +`system.process.count`. + +#### Do not use `total` + +UpDownCounters SHOULD NOT use `_total` because then they will look like +monotonic sums. + +Counters SHOULD NOT append `_total` either because then their meaning will +be confusing in delta backends. ## General Metric Semantic Conventions @@ -154,8 +188,10 @@ over all attribute values SHOULD be equal to the **limit**. - **utilization** - an instrument that measures the *fraction* of **usage** out of its **limit** should be called `entity.utilization`. For example, -`system.memory.utilization` for the fraction of memory in use. Utilization -values are in the range `[0, 1]`. +`system.memory.utilization` for the fraction of memory in use. Utilization can +be with respect to a fixed limit or a soft limit. Utilization values are +represended as a ratio and are typically in the range `[0, 1]`, but may go above 1 +in case of exceeding a soft limit. - **time** - an instrument that measures passage of time should be called `entity.time`. For example, `system.cpu.time` with attribute `state = idle | user @@ -224,4 +260,4 @@ For example, if you are tracking `active_requests` with an `UpDownCounter`, and request starts and decrementing it each time a request ends, then any attributes which are not yet available when incrementing the counter at request start should not be used when decrementing the counter at request end. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/general/reverse-proxy.png b/docs/general/reverse-proxy.png new file mode 100644 index 0000000000..2f21f817d8 Binary files /dev/null and b/docs/general/reverse-proxy.png differ diff --git a/docs/general/session.md b/docs/general/session.md new file mode 100644 index 0000000000..639b1c2044 --- /dev/null +++ b/docs/general/session.md @@ -0,0 +1,27 @@ +# Semantic conventions for session + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions to apply to client-side applications when tracking sessions. + +Session is defined as the period of time encompassing all activities performed by the application and the actions +executed by the end user. + +Consequently, a Session is represented as a collection of Logs, Events, and Spans emitted by the Client Application +throughout the Session's duration. Each Session is assigned a unique identifier, which is included as an attribute in +the Logs, Events, and Spans generated during the Session's lifecycle. + +When a session reaches end of life, typically due to user inactivity or session timeout, a new session identifier +will be assigned. The previous session identifier may be provided by the instrumentation so that telemetry +backends can link the two sessions. + +## Attributes + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`session.id`](/docs/attributes-registry/session.md) | string | A unique id to identify a session. | `00112233-4455-6677-8899-aabbccddeeff` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`session.previous_id`](/docs/attributes-registry/session.md) | string | The previous `session.id` for this user, when known. | `00112233-4455-6677-8899-aabbccddeeff` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/general/simple.png b/docs/general/simple.png new file mode 100644 index 0000000000..b8c48b0748 Binary files /dev/null and b/docs/general/simple.png differ diff --git a/docs/general/trace-compatibility.md b/docs/general/trace-compatibility.md index 77ed44a13b..ffe1fe34b9 100644 --- a/docs/general/trace-compatibility.md +++ b/docs/general/trace-compatibility.md @@ -24,19 +24,19 @@ with one of the accepted values, describing the direct causal relationships between a child Span and a parent Span, as defined by [OpenTracing](https://github.com/opentracing/specification/blob/master/specification.md). - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `opentracing.ref_type` | string | Parent-child Reference type [1] | `child_of` | Recommended | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`opentracing.ref_type`](/docs/attributes-registry/opentracing.md) | string | Parent-child Reference type [1] | `child_of`; `follows_from` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** The causal relationship between a child Span and a parent Span. -`opentracing.ref_type` MUST be one of the following: +`opentracing.ref_type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Value | Description | -|---|---| -| `child_of` | The parent Span depends on the child Span in some capacity | -| `follows_from` | The parent Span does not depend in any way on the result of the child Span | +| Value | Description | Stability | +|---|---|---| +| `child_of` | The parent Span depends on the child Span in some capacity | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `follows_from` | The parent Span doesn't depend in any way on the result of the child Span | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/general/trace.md b/docs/general/trace.md index af8e1c164e..ca9d88fa88 100644 --- a/docs/general/trace.md +++ b/docs/general/trace.md @@ -5,7 +5,7 @@ aliases: [docs/specs/semconv/general/trace-general] # Trace Semantic Conventions -**Status**: [Experimental][DocumentStatus] +**Status**: [Mixed][DocumentStatus] In OpenTelemetry spans can be created freely and it’s up to the implementor to annotate them with attributes specific to the represented operation. Spans @@ -26,7 +26,7 @@ The following semantic conventions for spans are defined: * [Cloud Providers](/docs/cloud-providers/README.md): Semantic Conventions for cloud providers spans. * [Database](/docs/database/database-spans.md): For SQL and NoSQL client call spans. * [Exceptions](/docs/exceptions/exceptions-spans.md): For recording exceptions associated with a span. -* [FaaS](/docs/faas/faas-spans.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans. +* [FaaS](/docs/faas/faas-spans.md): For [Function as a Service](https://wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans. * [Feature Flags](/docs/feature-flags/feature-flags-spans.md): For recording feature flag evaluations associated with a span. * [HTTP](/docs/http/http-spans.md): For HTTP client and server spans. * [Messaging](/docs/messaging/messaging-spans.md): For messaging systems (queues, publish/subscribe, etc.) spans. @@ -34,7 +34,7 @@ The following semantic conventions for spans are defined: * [RPC/RMI](/docs/rpc/rpc-spans.md): For remote procedure call (e.g., gRPC) spans. Apart from semantic conventions for traces, [metrics](metrics.md), [logs](logs.md), and [events](events.md), -OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md) with their own +OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/graphql/graphql-spans.md b/docs/graphql/graphql-spans.md new file mode 100644 index 0000000000..2dd2688405 --- /dev/null +++ b/docs/graphql/graphql-spans.md @@ -0,0 +1,35 @@ + + +# Semantic Conventions for GraphQL Server + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions to apply when instrumenting the GraphQL implementation. They map GraphQL +operations to attributes on a Span. + +The **span name** MUST be of the format ` ` provided that +`graphql.operation.type` and `graphql.operation.name` are available. If `graphql.operation.name` is not available, the +span SHOULD be named ``. When `` is not available, `GraphQL Operation` +MAY be used as span name. + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`graphql.document`](/docs/attributes-registry/graphql.md) | string | The GraphQL document being executed. [1] | `query findBookById { bookById(id: ?) { name } }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`graphql.operation.name`](/docs/attributes-registry/graphql.md) | string | The name of the operation being executed. | `findBookById` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`graphql.operation.type`](/docs/attributes-registry/graphql.md) | string | The type of the operation being executed. | `query`; `mutation`; `subscription` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The value may be sanitized to exclude sensitive information. + +`graphql.operation.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `query` | GraphQL query | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mutation` | GraphQL mutation | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `subscription` | GraphQL subscription | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/http/README.md b/docs/http/README.md index c12ecc2998..e6b4bb4f20 100644 --- a/docs/http/README.md +++ b/docs/http/README.md @@ -1,13 +1,13 @@ # Semantic Conventions for HTTP -**Status**: [Experimental, Feature-freeze][DocumentStatus] +**Status**: [Mixed][DocumentStatus] This document defines semantic conventions for HTTP spans, metrics and logs. They can be used for http and https schemes @@ -18,29 +18,30 @@ and various HTTP versions like 1.1, 2 and SPDY. > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) > (or prior): > -> * SHOULD NOT change the version of the HTTP or networking attributes that they emit +> * SHOULD NOT change the version of the HTTP or networking conventions that they emit > until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in HTTP instrumentations). +> include stabilization of a core set of networking conventions which are also used +> in HTTP instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable HTTP and networking attributes, -> and stop emitting the old experimental HTTP and networking attributes +> * `http` - emit the new, stable HTTP and networking conventions, +> and stop emitting the old experimental HTTP and networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable HTTP and networking attributes, +> * `http/dup` - emit both the old and the stable HTTP and networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental HTTP and networking attributes +> emitting whatever version of the old experimental HTTP and networking conventions > the instrumentation was emitting previously. +> * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). +> for at least six months after it starts emitting both sets of conventions. +> * SHOULD drop the environment variable in the next major version. Semantic conventions for HTTP are defined for the following signals: * [HTTP Spans](http-spans.md): Semantic Conventions for HTTP client and server *spans*. * [HTTP Metrics](http-metrics.md): Semantic Conventions for HTTP client and server *metrics*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 502d9e0a14..6f68efb10f 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -4,7 +4,7 @@ linkTitle: Metrics # Semantic Conventions for HTTP Metrics -**Status**: [Experimental, partial feature-freeze][DocumentStatus] +**Status**: [Mixed][DocumentStatus] The conventions described in this section are HTTP specific. When HTTP operations occur, metric events about those operations will be generated and reported to provide insight into the @@ -15,14 +15,17 @@ operations. By adding HTTP attributes to metric events it allows for finely tune - [HTTP Server](#http-server) - * [Metric: `http.server.duration`](#metric-httpserverduration) - * [Metric: `http.server.active_requests`](#metric-httpserveractive_requests) - * [Metric: `http.server.request.size`](#metric-httpserverrequestsize) - * [Metric: `http.server.response.size`](#metric-httpserverresponsesize) + - [Metric: `http.server.request.duration`](#metric-httpserverrequestduration) + - [Metric: `http.server.active_requests`](#metric-httpserveractive_requests) + - [Metric: `http.server.request.body.size`](#metric-httpserverrequestbodysize) + - [Metric: `http.server.response.body.size`](#metric-httpserverresponsebodysize) - [HTTP Client](#http-client) - * [Metric: `http.client.duration`](#metric-httpclientduration) - * [Metric: `http.client.request.size`](#metric-httpclientrequestsize) - * [Metric: `http.client.response.size`](#metric-httpclientresponsesize) + - [Metric: `http.client.request.duration`](#metric-httpclientrequestduration) + - [Metric: `http.client.request.body.size`](#metric-httpclientrequestbodysize) + - [Metric: `http.client.response.body.size`](#metric-httpclientresponsebodysize) + - [Metric: `http.client.open_connections`](#metric-httpclientopen_connections) + - [Metric: `http.client.connection.duration`](#metric-httpclientconnectionduration) + - [Metric: `http.client.active_requests`](#metric-httpclientactive_requests) @@ -31,67 +34,63 @@ operations. By adding HTTP attributes to metric events it allows for finely tune > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) > (or prior): > -> * SHOULD NOT change the version of the HTTP or networking attributes that they emit +> * SHOULD NOT change the version of the HTTP or networking conventions that they emit > until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in HTTP instrumentations). +> include stabilization of a core set of networking conventions which are also used +> in HTTP instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable HTTP and networking attributes, -> and stop emitting the old experimental HTTP and networking attributes +> * `http` - emit the new, stable HTTP and networking conventions, +> and stop emitting the old experimental HTTP and networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable HTTP and networking attributes, +> * `http/dup` - emit both the old and the stable HTTP and networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental HTTP and networking attributes +> emitting whatever version of the old experimental HTTP and networking conventions > the instrumentation was emitting previously. +> * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). +> for at least six months after it starts emitting both sets of conventions. +> * SHOULD drop the environment variable in the next major version. ## HTTP Server -### Metric: `http.server.duration` - -**Status**: [Experimental, Feature-freeze][DocumentStatus] +### Metric: `http.server.request.duration` This metric is required. When this metric is reported alongside an HTTP server span, the metric value SHOULD be the same as the HTTP server span duration. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/api.md#instrument-advice) -of `[ 0, 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 ]`. +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/metrics/api.md#instrument-advisory-parameters) +of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `http.server.duration` | Histogram | `s` | Measures the duration of inbound HTTP requests. | + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `http.server.request.duration` | Histogram | `s` | Duration of HTTP server requests. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | -| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | -| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | - -**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. -SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. [2] | `http`; `https` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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 request has ended with an error. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.response.status_code`](/docs/attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` If and only if one was received/sent. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.route`](/docs/attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [4] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` If and only if it's available | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [5] | `http`; `spdy` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER` and, except if reporting a metric, MUST -set the exact method received in the request line as value of the `http.request.method_original` attribute. +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named @@ -102,67 +101,89 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[2]:** The scheme of the original client request, if known (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request. + +**[3]:** If the request fails with an error before response status code was sent or received, +`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) +or a component-specific low cardinality error identifier. -**[4]:** Determined by using the first of the following that applies +If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. -- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only - include host identifier. -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Host identifier of the `Host` header +The `error.type` value SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. -SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +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. -**[5]:** Determined by using the first of the following that applies +If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -- Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. -- Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Port identifier of the `Host` header +**[4]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. + +**[5]:** The value SHOULD be normalized to lowercase. -`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +**[6]:** If not `http` and `network.protocol.version` is set. -| Value | Description | -|---|---| -| `CONNECT` | CONNECT method. | -| `DELETE` | DELETE method. | -| `GET` | GET method. | -| `HEAD` | HEAD method. | -| `OPTIONS` | OPTIONS method. | -| `PATCH` | PATCH method. | -| `POST` | POST method. | -| `PUT` | PUT method. | -| `TRACE` | TRACE method. | -| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | +**[7]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. + +**[8]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +> **Warning** +> Since this attribute is based on HTTP headers, opting in to it may allow an attacker +> to trigger cardinality limits, degrading the usefulness of the metric. + +**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +> **Warning** +> Since this attribute is based on HTTP headers, opting in to it may allow an attacker +> to trigger cardinality limits, degrading the usefulness of the metric. + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `CONNECT` | CONNECT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `DELETE` | DELETE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `GET` | GET method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `HEAD` | HEAD method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `OPTIONS` | OPTIONS method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PATCH` | PATCH method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `POST` | POST method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`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) | ### Metric: `http.server.active_requests` -**Status**: [Experimental][DocumentStatus] - This metric is optional. -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `http.server.active_requests` | UpDownCounter | `{request}` | Measures the number of concurrent HTTP requests that are currently in-flight. | +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `http.server.active_requests` | UpDownCounter | `{request}` | Number of active HTTP server requests. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [2] | `example.com` | Opt-In | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [3] | `80`; `8080`; `443` | Opt-In | -| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [3] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER` and, except if reporting a metric, MUST -set the exact method received in the request line as value of the `http.request.method_original` attribute. +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named @@ -173,72 +194,62 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[2]:** Determined by using the first of the following that applies - -- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only - include host identifier. -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Host identifier of the `Host` header - -SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. - -**[3]:** Determined by using the first of the following that applies - -- Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. -- Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Port identifier of the `Host` header - -`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. - -| Value | Description | -|---|---| -| `CONNECT` | CONNECT method. | -| `DELETE` | DELETE method. | -| `GET` | GET method. | -| `HEAD` | HEAD method. | -| `OPTIONS` | OPTIONS method. | -| `PATCH` | PATCH method. | -| `POST` | POST method. | -| `PUT` | PUT method. | -| `TRACE` | TRACE method. | -| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | - +**[2]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +> **Warning** +> Since this attribute is based on HTTP headers, opting in to it may allow an attacker +> to trigger cardinality limits, degrading the usefulness of the metric. -### Metric: `http.server.request.size` +**[3]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +> **Warning** +> Since this attribute is based on HTTP headers, opting in to it may allow an attacker +> to trigger cardinality limits, degrading the usefulness of the metric. + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `CONNECT` | CONNECT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `DELETE` | DELETE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `GET` | GET method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `HEAD` | HEAD method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `OPTIONS` | OPTIONS method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PATCH` | PATCH method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `POST` | POST method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + -**Status**: [Experimental][DocumentStatus] +### Metric: `http.server.request.body.size` This metric is optional. - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `http.server.request.size` | Histogram | `By` | Measures the size of HTTP request messages (compressed). | + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `http.server.request.body.size` | Histogram | `By` | Size of HTTP server request bodies. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | -| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | -| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | - -**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. -SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. [2] | `http`; `https` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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 request has ended with an error. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.response.status_code`](/docs/attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` If and only if one was received/sent. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.route`](/docs/attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [4] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` If and only if it's available | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [5] | `http`; `spdy` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER` and, except if reporting a metric, MUST -set the exact method received in the request line as value of the `http.request.method_original` attribute. +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named @@ -249,74 +260,96 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[2]:** The scheme of the original client request, if known (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request. -**[4]:** Determined by using the first of the following that applies +**[3]:** If the request fails with an error before response status code was sent or received, +`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) +or a component-specific low cardinality error identifier. -- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only - include host identifier. -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Host identifier of the `Host` header +If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. -SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. +The `error.type` value SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. -**[5]:** Determined by using the first of the following that applies +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +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. -- Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. -- Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Port identifier of the `Host` header +If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +**[4]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. -| Value | Description | -|---|---| -| `CONNECT` | CONNECT method. | -| `DELETE` | DELETE method. | -| `GET` | GET method. | -| `HEAD` | HEAD method. | -| `OPTIONS` | OPTIONS method. | -| `PATCH` | PATCH method. | -| `POST` | POST method. | -| `PUT` | PUT method. | -| `TRACE` | TRACE method. | -| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | - +**[5]:** The value SHOULD be normalized to lowercase. -### Metric: `http.server.response.size` +**[6]:** If not `http` and `network.protocol.version` is set. -**Status**: [Experimental][DocumentStatus] +**[7]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. + +**[8]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +> **Warning** +> Since this attribute is based on HTTP headers, opting in to it may allow an attacker +> to trigger cardinality limits, degrading the usefulness of the metric. + +**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +> **Warning** +> Since this attribute is based on HTTP headers, opting in to it may allow an attacker +> to trigger cardinality limits, degrading the usefulness of the metric. + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `CONNECT` | CONNECT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `DELETE` | DELETE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `GET` | GET method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `HEAD` | HEAD method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `OPTIONS` | OPTIONS method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PATCH` | PATCH method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `POST` | POST method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`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) | + + +### Metric: `http.server.response.body.size` This metric is optional. - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `http.server.response.size` | Histogram | `By` | Measures the size of HTTP response messages (compressed). | + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `http.server.response.body.size` | Histogram | `By` | Size of HTTP server response bodies. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | -| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | -| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | - -**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. -SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. [2] | `http`; `https` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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 request has ended with an error. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.response.status_code`](/docs/attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` If and only if one was received/sent. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.route`](/docs/attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [4] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` If and only if it's available | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [5] | `http`; `spdy` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER` and, except if reporting a metric, MUST -set the exact method received in the request line as value of the `http.request.method_original` attribute. +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named @@ -327,78 +360,101 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[2]:** The scheme of the original client request, if known (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request. + +**[3]:** If the request fails with an error before response status code was sent or received, +`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) +or a component-specific low cardinality error identifier. + +If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. + +The `error.type` value SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +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. -**[4]:** Determined by using the first of the following that applies +If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only - include host identifier. -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Host identifier of the `Host` header +**[4]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. -SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. +**[5]:** The value SHOULD be normalized to lowercase. -**[5]:** Determined by using the first of the following that applies +**[6]:** If not `http` and `network.protocol.version` is set. -- Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. -- Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Port identifier of the `Host` header +**[7]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +**[8]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +> **Warning** +> Since this attribute is based on HTTP headers, opting in to it may allow an attacker +> to trigger cardinality limits, degrading the usefulness of the metric. -| Value | Description | -|---|---| -| `CONNECT` | CONNECT method. | -| `DELETE` | DELETE method. | -| `GET` | GET method. | -| `HEAD` | HEAD method. | -| `OPTIONS` | OPTIONS method. | -| `PATCH` | PATCH method. | -| `POST` | POST method. | -| `PUT` | PUT method. | -| `TRACE` | TRACE method. | -| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | +**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +> **Warning** +> Since this attribute is based on HTTP headers, opting in to it may allow an attacker +> to trigger cardinality limits, degrading the usefulness of the metric. + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `CONNECT` | CONNECT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `DELETE` | DELETE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `GET` | GET method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `HEAD` | HEAD method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `OPTIONS` | OPTIONS method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PATCH` | PATCH method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `POST` | POST method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`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) | ## HTTP Client -### Metric: `http.client.duration` - -**Status**: [Experimental, Feature-freeze][DocumentStatus] +### Metric: `http.client.request.duration` This metric is required. When this metric is reported alongside an HTTP client span, the metric value SHOULD be the same as the HTTP client span duration. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/api.md#instrument-advice) -of `[ 0, 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 ]`. +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/metrics/api.md#instrument-advisory-parameters) +of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `http.client.duration` | Histogram | `s` | Measures the duration of outbound HTTP requests. | + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `http.client.request.duration` | Histogram | `s` | Duration of HTTP client requests. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | -| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [4] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If request has ended with an error. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.response.status_code`](/docs/attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` If and only if one was received/sent. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [5] | `http`; `spdy` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER` and, except if reporting a metric, MUST -set the exact method received in the request line as value of the `http.request.method_original` attribute. +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named @@ -409,65 +465,84 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. -**[3]:** Determined by using the first of the following that applies +**[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. -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form -- Host identifier of the `Host` header +**[4]:** If the request fails with an error before response status code was sent or received, +`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) +or a component-specific low cardinality error identifier. -SHOULD NOT be set if capturing it would require an extra DNS lookup. +If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. -**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. +The `error.type` value SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +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. -`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -| Value | Description | -|---|---| -| `CONNECT` | CONNECT method. | -| `DELETE` | DELETE method. | -| `GET` | GET method. | -| `HEAD` | HEAD method. | -| `OPTIONS` | OPTIONS method. | -| `PATCH` | PATCH method. | -| `POST` | POST method. | -| `PUT` | PUT method. | -| `TRACE` | TRACE method. | -| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | - +**[5]:** The value SHOULD be normalized to lowercase. -### Metric: `http.client.request.size` +**[6]:** If not `http` and `network.protocol.version` is set. -**Status**: [Experimental][DocumentStatus] +**[7]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `CONNECT` | CONNECT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `DELETE` | DELETE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `GET` | GET method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `HEAD` | HEAD method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `OPTIONS` | OPTIONS method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PATCH` | PATCH method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `POST` | POST method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`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) | + + +### Metric: `http.client.request.body.size` This metric is optional. - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `http.client.request.size` | Histogram | `By` | Measures the size of HTTP request messages (compressed). | + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `http.client.request.body.size` | Histogram | `By` | Size of HTTP client request bodies. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | -| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [4] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If request has ended with an error. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.response.status_code`](/docs/attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` If and only if one was received/sent. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [5] | `http`; `spdy` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER` and, except if reporting a metric, MUST -set the exact method received in the request line as value of the `http.request.method_original` attribute. +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named @@ -478,65 +553,84 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. -**[3]:** Determined by using the first of the following that applies +**[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. -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form -- Host identifier of the `Host` header +**[4]:** If the request fails with an error before response status code was sent or received, +`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) +or a component-specific low cardinality error identifier. -SHOULD NOT be set if capturing it would require an extra DNS lookup. +If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. -**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. +The `error.type` value SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +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. -`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -| Value | Description | -|---|---| -| `CONNECT` | CONNECT method. | -| `DELETE` | DELETE method. | -| `GET` | GET method. | -| `HEAD` | HEAD method. | -| `OPTIONS` | OPTIONS method. | -| `PATCH` | PATCH method. | -| `POST` | POST method. | -| `PUT` | PUT method. | -| `TRACE` | TRACE method. | -| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | - +**[5]:** The value SHOULD be normalized to lowercase. -### Metric: `http.client.response.size` +**[6]:** If not `http` and `network.protocol.version` is set. -**Status**: [Experimental][DocumentStatus] +**[7]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `CONNECT` | CONNECT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `DELETE` | DELETE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `GET` | GET method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `HEAD` | HEAD method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `OPTIONS` | OPTIONS method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PATCH` | PATCH method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `POST` | POST method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`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) | + + +### Metric: `http.client.response.body.size` This metric is optional. - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `http.client.response.size` | Histogram | `By` | Measures the size of HTTP response messages (compressed). | + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `http.client.response.body.size` | Histogram | `By` | Size of HTTP client response bodies. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | -| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [4] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If request has ended with an error. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.response.status_code`](/docs/attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` If and only if one was received/sent. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [5] | `http`; `spdy` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER` and, except if reporting a metric, MUST -set the exact method received in the request line as value of the `http.request.method_original` attribute. +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named @@ -547,34 +641,172 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. + +**[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]:** If the request fails with an error before response status code was sent or received, +`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) +or a component-specific low cardinality error identifier. + +If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. + +The `error.type` value SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +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 request has completed successfully, instrumentations SHOULD NOT set `error.type`. + +**[5]:** The value SHOULD be normalized to lowercase. + +**[6]:** If not `http` and `network.protocol.version` is set. + +**[7]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `CONNECT` | CONNECT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `DELETE` | DELETE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `GET` | GET method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `HEAD` | HEAD method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `OPTIONS` | OPTIONS method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PATCH` | PATCH method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `POST` | POST method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`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) | + + +### Metric: `http.client.open_connections` + +This metric is optional. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `http.client.open_connections` | UpDownCounter | `{connection}` | Number of outbound HTTP connections that are currently active or idle on the client. | ![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 | +|---|---|---|---|---|---| +| [`http.connection.state`](/docs/attributes-registry/http.md) | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | `Required` | ![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. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `80`; `8080`; `443` | `Required` | ![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. | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [3] | `1.1`; `2` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + +**[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. + +**[3]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. + +`http.connection.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `active` | active state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `idle` | idle state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `http.client.connection.duration` -**[3]:** Determined by using the first of the following that applies +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.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. + +This metric is optional. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `http.client.connection.duration` | Histogram | `s` | The duration of the successfully established outbound HTTP connections. | ![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 | +|---|---|---|---|---|---| +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `80`; `8080`; `443` | `Required` | ![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. | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [3] | `1.1`; `2` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + +**[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. + +**[3]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. + + +### Metric: `http.client.active_requests` + +**Status**: [Experimental][DocumentStatus] + +This metric is optional. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `http.client.active_requests` | UpDownCounter | `{request}` | Number of active HTTP requests. | ![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 | +|---|---|---|---|---|---| +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `80`; `8080`; `443` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form -- Host identifier of the `Host` header +**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -SHOULD NOT be set if capturing it would require an extra DNS lookup. +**[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. + +**[3]:** HTTP request method value SHOULD be "known" to the instrumentation. +By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override +the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named +OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods +(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). -`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. +Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. +Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -| Value | Description | -|---|---| -| `CONNECT` | CONNECT method. | -| `DELETE` | DELETE method. | -| `GET` | GET method. | -| `HEAD` | HEAD method. | -| `OPTIONS` | OPTIONS method. | -| `PATCH` | PATCH method. | -| `POST` | POST method. | -| `PUT` | PUT method. | -| `TRACE` | TRACE method. | -| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `CONNECT` | CONNECT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `DELETE` | DELETE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `GET` | GET method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `HEAD` | HEAD method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `OPTIONS` | OPTIONS method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PATCH` | PATCH method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `POST` | POST method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 946e1be2ca..91c060240c 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -4,7 +4,7 @@ linkTitle: Spans # Semantic Conventions for HTTP Spans -**Status**: [Experimental, Feature-freeze][DocumentStatus] +**Status**: [Stable][DocumentStatus], Unless otherwise specified. This document defines semantic conventions for HTTP client and server Spans. They can be used for http and https schemes @@ -16,19 +16,25 @@ and various HTTP versions like 1.1, 2 and SPDY. - [Name](#name) - [Status](#status) -- [Common Attributes](#common-attributes) - * [HTTP request and response headers](#http-request-and-response-headers) - [HTTP client](#http-client) - * [HTTP client span duration](#http-client-span-duration) - * [HTTP request retries and redirects](#http-request-retries-and-redirects) + - [HTTP client experimental attributes](#http-client-experimental-attributes) + - [HTTP client span duration](#http-client-span-duration) + - [HTTP request retries and redirects](#http-request-retries-and-redirects) - [HTTP server](#http-server) - * [HTTP server definitions](#http-server-definitions) - * [HTTP Server semantic conventions](#http-server-semantic-conventions) + - [HTTP server definitions](#http-server-definitions) + - [Setting `server.address` and `server.port` attributes](#setting-serveraddress-and-serverport-attributes) + - [Simple client/server example](#simple-clientserver-example) + - [Client/server example with reverse proxy](#clientserver-example-with-reverse-proxy) + - [HTTP server semantic conventions](#http-server-semantic-conventions) + - [HTTP server experimental attributes](#http-server-experimental-attributes) - [Examples](#examples) - * [HTTP client-server example](#http-client-server-example) - * [HTTP client retries examples](#http-client-retries-examples) - * [HTTP client authorization retry examples](#http-client-authorization-retry-examples) - * [HTTP client redirects examples](#http-client-redirects-examples) + - [HTTP client-server example](#http-client-server-example) + - [HTTP client retries examples](#http-client-retries-examples) + - [HTTP client authorization retry examples](#http-client-authorization-retry-examples) + - [HTTP client redirects examples](#http-client-redirects-examples) + - [HTTP client call: DNS error](#http-client-call-dns-error) + - [HTTP client call: Internal Server Error](#http-client-call-internal-server-error) + - [HTTP server call: connection dropped before response body was sent](#http-server-call-connection-dropped-before-response-body-was-sent) @@ -37,43 +43,54 @@ and various HTTP versions like 1.1, 2 and SPDY. > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) > (or prior): > -> * SHOULD NOT change the version of the HTTP or networking attributes that they emit +> * SHOULD NOT change the version of the HTTP or networking conventions that they emit > until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in HTTP instrumentations). +> include stabilization of a core set of networking conventions which are also used +> in HTTP instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable HTTP and networking attributes, -> and stop emitting the old experimental HTTP and networking attributes +> * `http` - emit the new, stable HTTP and networking conventions, +> and stop emitting the old experimental HTTP and networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable HTTP and networking attributes, +> * `http/dup` - emit both the old and the stable HTTP and networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental HTTP and networking attributes +> emitting whatever version of the old experimental HTTP and networking conventions > the instrumentation was emitting previously. +> * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). +> for at least six months after it starts emitting both sets of conventions. +> * SHOULD drop the environment variable in the next major version. ## Name -HTTP spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#span). -HTTP server span names SHOULD be `{http.request.method} {http.route}` if there is a -(low-cardinality) `http.route` available. -HTTP server span names SHOULD be `{http.request.method}` if there is no (low-cardinality) -`http.route` available. +HTTP spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/trace/api.md#span). + + + +HTTP server span names SHOULD be `{method} {http.route}` if there is a +(low-cardinality) `http.route` available (see below for the exact definition of the [`{method}`](#method-placeholder) placeholder). + +If there is no (low-cardinality) `http.route` available, HTTP server span names +SHOULD be [`{method}`](#method-placeholder). + HTTP client spans have no `http.route` attribute since client-side instrumentation -is not generally aware of the "route", and therefore HTTP client spans SHOULD use -`{http.request.method}`. +is not generally aware of the "route", and therefore HTTP client span names SHOULD be +[`{method}`](#method-placeholder). + + +The `{method}` MUST be `{http.request.method}` if the method represents the original method known to the instrumentation. +In other cases (when `{http.request.method}` is set to `_OTHER`), `{method}` MUST be `HTTP`. + Instrumentation MUST NOT default to using URI path as span name, but MAY provide hooks to allow custom logic to override the default span name. ## Status -[Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#set-status) MUST be left unset if HTTP status code was in the +[Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/trace/api.md#set-status) MUST be left unset if HTTP status code was in the 1xx, 2xx or 3xx ranges, unless there was another error (e.g., network error receiving the response body; or 3xx codes with max redirects exceeded), in which case status MUST be set to `Error`. @@ -86,34 +103,52 @@ failed to interpret, span status MUST be set to `Error`. Don't set the span status description if the reason can be inferred from `http.response.status_code`. -## Common Attributes - -The common attributes listed in this section apply to both HTTP clients and servers in addition to -the specific attributes listed in the [HTTP client](#http-client) and [HTTP server](#http-server) -sections below. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| `http.request.method_original` | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | Conditionally Required: [1] | -| `http.request.body.size` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | -| `http.response.body.size` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | -| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `spdy` | Recommended: if not default (`http`). | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `1.0`; `1.1`; `2.0` | Recommended | -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Conditionally Required: [4] | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| `user_agent.original` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended | - -**[1]:** If and only if it's different than `http.request.method`. - -**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. +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. + +## HTTP client + +This span type represents an outbound HTTP request. There are two ways this can be achieved in an instrumentation: + +1. Instrumentations SHOULD create an HTTP span for each attempt to send an HTTP request over the wire. + In case the request is resent, the resend attempts MUST follow the [HTTP resend spec](#http-request-retries-and-redirects). + In this case, instrumentations SHOULD NOT (also) emit a logical encompassing HTTP client span. + +2. If for some reason it is not possible to emit a span for each send attempt (because e.g. the instrumented library does not expose hooks that would allow this), + instrumentations MAY create an HTTP span for the top-most operation of the HTTP client. + In this case, the `url.full` MUST be the absolute URL that was originally requested, before any HTTP-redirects that may happen when executing the request. + +For an HTTP client span, `SpanKind` MUST be `Client`. + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.full`](/docs/attributes-registry/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [4] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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 request has ended with an error. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.request.method_original`](/docs/attributes-registry/http.md) | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.response.status_code`](/docs/attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` If and only if one was received/sent. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [7] | `http`; `spdy` | `Conditionally Required` [8] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.request.resend_count`](/docs/attributes-registry/http.md) | int | The ordinal number of request resending attempt (for any reason, including redirects). [9] | `3` | `Recommended` if and only if request was retried. | ![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. | `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 `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [10] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.request.header.`](/docs/attributes-registry/http.md) | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [11] | `http.request.header.content-type=["application/json"]`; `http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.response.header.`](/docs/attributes-registry/http.md) | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [12] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [13] | `tcp`; `udp` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1`; `YourApp/1.0.0 grpc-java-okhttp/1.27.2` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER` and, except if reporting a metric, MUST -set the exact method received in the request line as value of the `http.request.method_original` attribute. +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named @@ -124,116 +159,104 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. - -**[4]:** If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). +**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. -Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: +**[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. -* `http.request.method` +**[4]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. +`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. -`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +**[5]:** If the request fails with an error before response status code was sent or received, +`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) +or a component-specific low cardinality error identifier. -| Value | Description | -|---|---| -| `CONNECT` | CONNECT method. | -| `DELETE` | DELETE method. | -| `GET` | GET method. | -| `HEAD` | HEAD method. | -| `OPTIONS` | OPTIONS method. | -| `PATCH` | PATCH method. | -| `POST` | POST method. | -| `PUT` | PUT method. | -| `TRACE` | TRACE method. | -| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | +If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. -`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +The `error.type` value SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. -| Value | Description | -|---|---| -| `tcp` | TCP | -| `udp` | UDP | -| `pipe` | Named or anonymous pipe. See note below. | -| `unix` | Unix domain socket | +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +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. -`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -| Value | Description | -|---|---| -| `ipv4` | IPv4 | -| `ipv6` | IPv6 | - +**[6]:** If and only if it's different than `http.request.method`. -### HTTP request and response headers +**[7]:** The value SHOULD be normalized to lowercase. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|-------------------| -| `http.request.header.` | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [1] [2] | `http.request.header.content_type=["application/json"]`; `http.request.header.x_forwarded_for=["1.2.3.4", "1.2.3.5"]` | Opt-In | -| `http.response.header.` | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [1] [2] | `http.response.header.content_type=["application/json"]`; `http.response.header.my_custom_header=["abc", "def"]` | Opt-In | +**[8]:** If not `http` and `network.protocol.version` is set. -**[1]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. -Including all request/response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +**[9]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other). -The `User-Agent` header is already captured in the `user_agent.original` attribute. -Users MAY explicitly configure instrumentations to capture them even though it is not recommended. +**[10]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[2]:** The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. +**[11]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +The `User-Agent` header is already captured in the `user_agent.original` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. +The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. -## HTTP client - -This span type represents an outbound HTTP request. There are two ways this can be achieved in an instrumentation: - -1. Instrumentations SHOULD create an HTTP span for each attempt to send an HTTP request over the wire. - In case the request is resent, the resend attempts MUST follow the [HTTP resend spec](#http-request-retries-and-redirects). - In this case, instrumentations SHOULD NOT (also) emit a logical encompassing HTTP client span. - -2. If for some reason it is not possible to emit a span for each send attempt (because e.g. the instrumented library does not expose hooks that would allow this), - instrumentations MAY create an HTTP span for the top-most operation of the HTTP client. - In this case, the `url.full` MUST be the absolute URL that was originally requested, before any HTTP-redirects that may happen when executing the request. - -For an HTTP client span, `SpanKind` MUST be `Client`. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [1] | `3` | Recommended: if and only if request was retried. | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | -| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | -| [`server.socket.domain`](../general/attributes.md) | string | The domain name of an immediate peer. [5] | `proxy.example.com` | Recommended: If different than `server.address`. | -| [`server.socket.port`](../general/attributes.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | -| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [6] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Required | - -**[1]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other). - -**[2]:** Determined by using the first of the following that applies - -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form -- Host identifier of the `Host` header - -If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then -`server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. - -**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. - -**[4]:** If not default (`80` for `http` scheme, `443` for `https`). +**[12]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +Users MAY explicitly configure instrumentations to capture them even though it is not recommended. +The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. + +**[13]:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible. + +The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): + +* [`http.request.method`](/docs/attributes-registry/http.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) +* [`url.full`](/docs/attributes-registry/url.md) + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `CONNECT` | CONNECT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `DELETE` | DELETE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `GET` | GET method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `HEAD` | HEAD method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `OPTIONS` | OPTIONS method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PATCH` | PATCH method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `POST` | POST method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`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) | + +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + -**[5]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. +### HTTP client experimental attributes -**[6]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. -`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`. -`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes. +**Status**: [Experimental][DocumentStatus] -Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: +Instrumentations MAY allow users to enable additional experimental attributes. -* [`server.address`](../general/attributes.md) -* [`server.port`](../general/attributes.md) -* [`url.full`](../url/url.md) + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`http.request.body.size`](/docs/attributes-registry/http.md) | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`http.request.size`](/docs/attributes-registry/http.md) | int | The total size of the request in bytes. This should be the total number of bytes sent over the wire, including the request line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and request body if any. | `1437` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`http.response.body.size`](/docs/attributes-registry/http.md) | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`http.response.size`](/docs/attributes-registry/http.md) | int | The total size of the response in bytes. This should be the total number of bytes sent over the wire, including the status line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and response body and trailers if any. | `1437` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -Note that in some cases host and port identifiers in the `Host` header might be different from the `server.address` and `server.port`, in this case instrumentation MAY populate `Host` header on `http.request.header.host` attribute even if it's not enabled by user. - ### HTTP client span duration There are some minimal constraints that SHOULD be honored: @@ -256,7 +279,7 @@ Retries and redirects cause more than one physical HTTP request to be sent. A request is resent when an HTTP client library sends more than one HTTP request to satisfy the same API call. This may happen due to following redirects, authorization challenges, 503 Server Unavailable, network issues, or any other. -Each time an HTTP request is resent, the `http.resend_count` attribute SHOULD be added to each repeated span and set to the ordinal number of the request resend attempt. +Each time an HTTP request is resent, the `http.request.resend_count` attribute SHOULD be added to each repeated span and set to the ordinal number of the request resend attempt. See the examples for more details about: @@ -266,138 +289,224 @@ See the examples for more details about: ## HTTP server -To understand the attributes defined in this section, it is helpful to read the "Definitions" subsection. +Read the following section to understand how HTTP server instrumentations are suggested to capture server information. ### HTTP server definitions -This section gives a short summary of some concepts -in web server configuration and web app deployment -that are relevant to tracing. +An HTTP request can be routed to a specific HTTP application via intermediaries such as reverse proxies. +HTTP requests sent to the same domain name may be handled by multiple applications depending on the port, path, headers, or other parameters. + +For example, different versions of the same web-application can run side-by-side as independent applications behind the reverse proxy which routes request to one or another based on the request path. + +Instances of different HTTP server applications may run on the same physical host and share the same IP address, but listen to different TCP/UDP ports. +In order to route the request to a specific application, reverse proxies usually modify the [HTTP Host header][Host and authority] replacing the original value provided by the client with an actual proxied server name. This behavior depends on the reverse proxy configuration. In some cases, the `Host` header is not used when routing request to a specific application, making it prone to having bogus content. -Usually, on a physical host, reachable by one or multiple IP addresses, a single HTTP listener process runs. -If multiple processes are running, they must listen on distinct TCP/UDP ports so that the OS can route incoming TCP/UDP packets to the right one. +HTTP server frameworks and their instrumentations have limited knowledge about the HTTP infrastructure and intermediaries that requests go through. In a general case, they can only use HTTP request properties such as request target or headers to populate `server.*` attributes. -Within a single server process, there can be multiple **virtual hosts**. -The [HTTP host header][] (in combination with a port number) is normally used to determine to which of them to route incoming HTTP requests. +#### Setting `server.address` and `server.port` attributes -The host header value that matches some virtual host is called the virtual hosts's **server name**. If there are multiple aliases for the virtual host, one of them (often the first one listed in the configuration) is called the **primary server name**. See for example, the Apache [`ServerName`][ap-sn] or NGINX [`server_name`][nx-sn] directive or the CGI specification on `SERVER_NAME` ([RFC 3875][rfc-servername]). -In practice the HTTP host header is often ignored when just a single virtual host is configured for the IP. +In the context of HTTP server, `server.address` and `server.port` attributes capture the original host name and port. They are intended, whenever possible, to be the same on the client and server sides. -Within a single virtual host, some servers support the concepts of an **HTTP application** -(for example in Java, the Servlet JSR defines an application as -"a collection of servlets, HTML pages, classes, and other resources that make up a complete application on a Web server" --- SRV.9 in [JSR 53][]; -in a deployment of a Python application to Apache, the application would be the [PEP 3333][] conformant callable that is configured using the -[`WSGIScriptAlias` directive][modwsgisetup] of `mod_wsgi`). +HTTP server instrumentations SHOULD do the best effort when populating `server.address` and `server.port` attributes and SHOULD determine them by using the first of the following that applies: -An application can be "mounted" under an **application root** -(also known as a *[context root][]*, *[context prefix][]*, or *[document base][]*) -which is a fixed path prefix of the URL that determines to which application a request is routed -(e.g., the server could be configured to route all requests that go to an URL path starting with `/webshop/` -at a particular virtual host -to the `com.example.webshop` web application). +* The original host which may be passed by the reverse proxy in the [`Forwarded#host`][Forwarded#host], [`X-Forwarded-Host`][X-Forwarded-Host], or a similar header. +* The [`:authority`][HTTP/2 authority] pseudo-header in case of HTTP/2 or HTTP/3 +* The [`Host`][Host header] header. -Some servers allow to bind the same HTTP application to multiple `(virtual host, application root)` pairs. +> **Note**: The `Host` and `:authority` headers contain host and port number of the server. The same applies to the `host` identifier of `Forwarded` header or the `X-Forwarded-Host` header. Instrumentations SHOULD populate both `server.address` and `server.port` attributes by parsing the value of corresponding header. -> TODO: Find way to trace HTTP application and application root ([opentelemetry/opentelementry-specification#335][]) +Application developers MAY overwrite potentially inaccurate values of `server.*` attributes using a [SpanProcessor][SpanProcessor] and MAY capture private host information using applicable [resource attributes](/docs/resource/README.md). -[HTTP host header]: https://tools.ietf.org/html/rfc7230#section-5.4 -[PEP 3333]: https://www.python.org/dev/peps/pep-3333/ -[modwsgisetup]: https://modwsgi.readthedocs.io/en/develop/user-guides/quick-configuration-guide.html -[context root]: https://docs.jboss.org/jbossas/guides/webguide/r2/en/html/ch06.html -[context prefix]: https://marc.info/?l=apache-cvs&m=130928191414740 -[document base]: http://tomcat.apache.org/tomcat-5.5-doc/config/context.html -[rfc-servername]: https://tools.ietf.org/html/rfc3875#section-4.1.14 -[ap-sn]: https://httpd.apache.org/docs/2.4/mod/core.html#servername -[nx-sn]: http://nginx.org/en/docs/http/ngx_http_core_module.html#server_name -[JSR 53]: https://jcp.org/aboutJava/communityprocess/maintenance/jsr053/index2.html -[opentelemetry/opentelementry-specification#335]: https://github.com/open-telemetry/opentelemetry-specification/issues/335 +#### Simple client/server example -### HTTP Server semantic conventions +![simple-http-server.png](simple-http-server.png) + +#### Client/server example with reverse proxy + +![reverse-proxy-http-server.png](reverse-proxy-http-server.png) + +[Host and authority]: https://tools.ietf.org/html/rfc9110#section-7.2 +[Host header]: https://tools.ietf.org/html/rfc7230#section-5.4 +[HTTP/2 authority]: https://tools.ietf.org/html/rfc9113#section-8.3.1 +[Forwarded#host]: https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#host +[X-Forwarded-Host]: https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Host + +### HTTP server semantic conventions This span type represents an inbound HTTP request. For an HTTP server span, `SpanKind` MUST be `Server`. -Given an inbound request for a route (e.g. `"/users/:userID?"`) the `name` attribute of the span SHOULD be set to this route. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.path`](/docs/attributes-registry/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [2] | `/search` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. [3] | `http`; `https` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [4] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If request has ended with an error. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.request.method_original`](/docs/attributes-registry/http.md) | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | `Conditionally Required` [5] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.response.status_code`](/docs/attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` If and only if one was received/sent. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.route`](/docs/attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [6] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` If and only if it's available | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [7] | `http`; `spdy` | `Conditionally Required` [8] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.query`](/docs/attributes-registry/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [10] | `q=OpenTelemetry` | `Conditionally Required` If and only if one was received/sent. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`client.address`](/docs/attributes-registry/client.md) | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [11] | `83.164.160.102` | `Recommended` | ![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. | `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 `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [12] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [13] | `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 | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1`; `YourApp/1.0.0 grpc-java-okhttp/1.27.2` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`client.port`](/docs/attributes-registry/client.md) | int | The port of whichever client was captured in `client.address`. [14] | `65123` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.request.header.`](/docs/attributes-registry/http.md) | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [15] | `http.request.header.content-type=["application/json"]`; `http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.response.header.`](/docs/attributes-registry/http.md) | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [16] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.local.address`](/docs/attributes-registry/network.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.local.port`](/docs/attributes-registry/network.md) | int | Local socket port. Useful in case of a multi-port host. | `65123` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [17] | `tcp`; `udp` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. +By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -If the route cannot be determined, the `name` attribute MUST be set as defined in the general semantic conventions for HTTP. +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| [`client.address`](../general/attributes.md) | string | Client address - unix domain socket name, IPv4 or IPv6 address. [2] | `83.164.160.102` | Recommended | -| [`client.port`](../general/attributes.md) | int | The port of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). Otherwise, the immediate client peer port. [3] | `65123` | Recommended | -| [`client.socket.address`](../general/attributes.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | -| [`client.socket.port`](../general/attributes.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Recommended: [6] | -| [`server.socket.address`](../general/attributes.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.5.3.2` | Opt-In | -| [`server.socket.port`](../general/attributes.md) | int | Local socket port. Useful in case of a multi-port host. | `16456` | Opt-In | -| [`url.path`](../url/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [7] | `/search` | Required | -| [`url.query`](../url/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [8] | `q=OpenTelemetry` | Conditionally Required: If and only if one was received/sent. | -| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | - -**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. -SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. +If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override +the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named +OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods +(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). -**[2]:** The IP address of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded), [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For), or a similar header). Otherwise, the immediate client peer address. +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. +Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. +Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. + +**[2]:** Sensitive content provided in `url.path` SHOULD be scrubbed when instrumentations can identify it. + +**[3]:** The scheme of the original client request, if known (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request. + +**[4]:** If the request fails with an error before response status code was sent or received, +`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) +or a component-specific low cardinality error identifier. -**[3]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent client port behind any intermediaries (e.g. proxies) if it's available. +If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. + +The `error.type` value SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +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 request has completed successfully, instrumentations SHOULD NOT set `error.type`. + +**[5]:** If and only if it's different than `http.request.method`. + +**[6]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. -**[4]:** Determined by using the first of the following that applies +**[7]:** The value SHOULD be normalized to lowercase. -- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only - include host identifier. -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Host identifier of the `Host` header +**[8]:** If not `http` and `network.protocol.version` is set. -SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. +**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). -**[5]:** Determined by using the first of the following that applies +**[10]:** Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it. -- Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. -- Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Port identifier of the `Host` header +**[11]:** The IP address of the original client behind all proxies, if known (e.g. from [Forwarded#for](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#for), [X-Forwarded-For](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-For), or a similar header). Otherwise, the immediate client peer address. -**[6]:** If not default (`80` for `http` scheme, `443` for `https`). +**[12]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[7]:** When missing, the value is assumed to be `/` +**[13]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). -**[8]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. +**[14]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. -Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: +**[15]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +The `User-Agent` header is already captured in the `user_agent.original` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. +The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. -* [`server.address`](../general/attributes.md) -* [`server.port`](../general/attributes.md) -* [`url.path`](../url/url.md) -* [`url.query`](../url/url.md) -* [`url.scheme`](../url/url.md) +**[16]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +Users MAY explicitly configure instrumentations to capture them even though it is not recommended. +The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. + +**[17]:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible. + +The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): + +* [`http.request.method`](/docs/attributes-registry/http.md) +* [`url.path`](/docs/attributes-registry/url.md) +* [`url.scheme`](/docs/attributes-registry/url.md) +* [`server.port`](/docs/attributes-registry/server.md) +* [`url.query`](/docs/attributes-registry/url.md) +* [`client.address`](/docs/attributes-registry/client.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`user_agent.original`](/docs/attributes-registry/user-agent.md) +* [`http.request.header.`](/docs/attributes-registry/http.md) + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `CONNECT` | CONNECT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `DELETE` | DELETE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `GET` | GET method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `HEAD` | HEAD method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `OPTIONS` | OPTIONS method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PATCH` | PATCH method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `POST` | POST method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`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) | + +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `http.route` MUST be provided at span creation time if and only if it's already available. If it becomes available after span starts, instrumentation MUST populate it anytime before span ends. -Note that in some cases host and port identifiers in the `Host` header might be different from the `server.address` and `server.port`, in this case instrumentation MAY populate `Host` header on `http.request.header.host` attribute even if it's not enabled by user. +### HTTP server experimental attributes + +**Status**: [Experimental][DocumentStatus] + +Instrumentations MAY allow users to enable additional experimental attributes. + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`http.request.body.size`](/docs/attributes-registry/http.md) | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`http.request.size`](/docs/attributes-registry/http.md) | int | The total size of the request in bytes. This should be the total number of bytes sent over the wire, including the request line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and request body if any. | `1437` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`http.response.body.size`](/docs/attributes-registry/http.md) | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`http.response.size`](/docs/attributes-registry/http.md) | int | The total size of the response in bytes. This should be the total number of bytes sent over the wire, including the status line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and response body and trailers if any. | `1437` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + ## Examples ### HTTP client-server example -As an example, if a browser request for `https://example.com:8080/webshop/articles/4?s=1` is invoked from a host with IP 192.0.2.4, we may have the following Span on the client side: +As an example, if a browser request for `https://example.com:8080/webshop/articles/4?s=1&t=2` is invoked from a host with IP 192.0.2.4, we may have the following Span on the client side: Span name: `GET` | Attribute name | Value | | :------------------- | :-------------------------------------------------------| | `http.request.method`| `"GET"` | -| `network.protocol.version` | `"1.1"` | -| `url.full` | `"https://example.com:8080/webshop/articles/4?s=1"` | +| `network.protocol.version` | `"1.1"` | +| `url.full` | `"https://example.com:8080/webshop/articles/4?s=1&t=2"` | | `server.address` | `example.com` | -| `server.port` | 8080 | -| `server.socket.address` | `"192.0.2.5"` | +| `server.port` | `8080` | +| `network.peer.address` | `"192.0.2.5"` | +| `network.peer.port` | `8080` | | `http.response.status_code` | `200` | The corresponding server Span may look like this: @@ -409,7 +518,7 @@ Span name: `GET /webshop/articles/:article_id`. | `http.request.method`| `"GET"` | | `network.protocol.version` | `"1.1"` | | `url.path` | `"/webshop/articles/4"` | -| `url.query` | `"?s=1"` | +| `url.query` | `"s=1&t=2"` | | `server.address` | `"example.com"` | | `server.port` | `8080` | | `url.scheme` | `"https"` | @@ -430,11 +539,11 @@ request (SERVER, trace=t1, span=s1) | | | --- server (SERVER, trace=t1, span=s3) | - -- GET / - 500 (CLIENT, trace=t1, span=s4, http.resend_count=1) + -- GET / - 500 (CLIENT, trace=t1, span=s4, http.request.resend_count=1) | | | --- server (SERVER, trace=t1, span=s5) | - -- GET / - 200 (CLIENT, trace=t1, span=s6, http.resend_count=2) + -- GET / - 200 (CLIENT, trace=t1, span=s6, http.request.resend_count=2) | --- server (SERVER, trace=t1, span=s7) ``` @@ -446,11 +555,11 @@ GET / - 500 (CLIENT, trace=t1, span=s1) | --- server (SERVER, trace=t1, span=s2) -GET / - 500 (CLIENT, trace=t2, span=s1, http.resend_count=1) +GET / - 500 (CLIENT, trace=t2, span=s1, http.request.resend_count=1) | --- server (SERVER, trace=t2, span=s2) -GET / - 200 (CLIENT, trace=t3, span=s1, http.resend_count=2) +GET / - 200 (CLIENT, trace=t3, span=s1, http.request.resend_count=2) | --- server (SERVER, trace=t3, span=s1) ``` @@ -466,7 +575,7 @@ request (SERVER, trace=t1, span=s1) | | | --- server (SERVER, trace=t1, span=s3) | - -- GET /hello - 200 (CLIENT, trace=t1, span=s4, http.resend_count=1) + -- GET /hello - 200 (CLIENT, trace=t1, span=s4, http.request.resend_count=1) | --- server (SERVER, trace=t1, span=s5) ``` @@ -478,7 +587,7 @@ GET /hello - 401 (CLIENT, trace=t1, span=s1) | --- server (SERVER, trace=t1, span=s2) -GET /hello - 200 (CLIENT, trace=t2, span=s1, http.resend_count=1) +GET /hello - 200 (CLIENT, trace=t2, span=s1, http.request.resend_count=1) | --- server (SERVER, trace=t2, span=s2) ``` @@ -494,7 +603,7 @@ request (SERVER, trace=t1, span=s1) | | | --- server (SERVER, trace=t1, span=s3) | - -- GET /hello - 200 (CLIENT, trace=t1, span=s4, http.resend_count=1) + -- GET /hello - 200 (CLIENT, trace=t1, span=s4, http.request.resend_count=1) | --- server (SERVER, trace=t1, span=s5) ``` @@ -506,9 +615,50 @@ GET / - 302 (CLIENT, trace=t1, span=s1) | --- server (SERVER, trace=t1, span=s2) -GET /hello - 200 (CLIENT, trace=t2, span=s1, http.resend_count=1) +GET /hello - 200 (CLIENT, trace=t2, span=s1, http.request.resend_count=1) | --- server (SERVER, trace=t2, span=s2) ``` -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +### HTTP client call: DNS error + +As an example, if a user requested `https://does-not-exist-123.com`, we may have the following span on the client side: + +| Attribute name | Value | +| :------------------- | :-------------------------------------------------------| +| `http.request.method`| `"GET"` | +| `network.protocol.version` | `"1.1"` | +| `url.full` | `"https://does-not-exist-123.com"` | +| `server.address` | `"does-not-exist-123.com"` | +| `error.type` | `"java.net.UnknownHostException"` | + +### HTTP client call: Internal Server Error + +As an example, if a user requested `https://example.com` and server returned 500, we may have the following span on the client side: + +| Attribute name | Value | +| :------------------- | :-------------------------------------------------------| +| `http.request.method`| `"GET"` | +| `network.protocol.version` | `"1.1"` | +| `url.full` | `"https://example.com"` | +| `server.address` | `"example.com"` | +| `http.response.status_code` | `500` | +| `error.type` | `"500"` | + +### HTTP server call: connection dropped before response body was sent + +As an example, if a user sent a `POST` request with a body to `https://example.com:8080/uploads/4`, we may see the following span on a server side: + +Span name: `POST /uploads/:document_id`. + +| Attribute name | Value | +| :------------------- | :---------------------------------------------- | +| `http.request.method`| `"GET"` | +| `url.path` | `"/uploads/4"` | +| `url.scheme` | `"https"` | +| `http.route` | `"/uploads/:document_id"` | +| `http.response.status_code` | `201` | +| `error.type` | `WebSocketDisconnect` | + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md +[SpanProcessor]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/trace/sdk.md#span-processor diff --git a/docs/http/migration-guide.md b/docs/http/migration-guide.md new file mode 100644 index 0000000000..65fea1a3fe --- /dev/null +++ b/docs/http/migration-guide.md @@ -0,0 +1,225 @@ +# HTTP semantic convention stability migration guide + +Due to the significant number of modifications and the extensive user base +affected by them, existing HTTP instrumentations published by +OpenTelemetry are required to implement a migration plan that will assist users in +transitioning to the stable HTTP semantic conventions. + +Specifically, when existing HTTP instrumentations published by OpenTelemetry are +updated to the stable HTTP semantic conventions, they: + +- SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` in + their existing major version, which accepts: + - `http` - emit the stable HTTP and networking conventions, and stop emitting + the old HTTP and networking conventions that the instrumentation emitted + previously. + - `http/dup` - emit both the old and the stable HTTP and networking + conventions, allowing for a phased rollout of the stable semantic + conventions. + - The default behavior (in the absence of one of these values) is to continue + emitting whatever version of the old HTTP and networking conventions the + instrumentation was emitting previously. +- Need to maintain (security patching at a minimum) their existing major version + for at least six months after it starts emitting both sets of conventions. +- May drop the environment variable in their next major version and emit only + the stable HTTP and networking conventions. + +## Summary of changes + +This section summarizes the changes made to the HTTP semantic conventions +from +[v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) +to +[v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/README.md). + +### Common attributes across HTTP client and server spans + + +| Change | Comments | +| --- | --- | +| `http.method` → `http.request.method` | Now captures only 9 common HTTP methods by default (configurable) plus `_OTHER` | +| `http.status_code` → `http.response.status_code` | | +| `http.request.header.` | • Dash (`"-"`) to underscore (`"_"`) normalization in `` has been removed
• On HTTP server spans: now must be provided to sampler | +| `http.response.header.` | Dash (`"-"`) to underscore (`"_"`) normalization in `` has been removed | +| `http.request_content_length` → `http.request.body.size` | • Recommended → Opt-In
• _Not marked stable yet_ | +| `http.response_content_length` → `http.response.body.size` | • Recommended → Opt-In
• _Not marked stable yet_ | +| `user_agent.original` | • On HTTP client spans: Recommended → Opt-In
• On HTTP server spans: now must be provided to sampler
• See note if [migrating from <= v1.18.0](#migrating-from--v1180) | +| `net.protocol.name` → `network.protocol.name` | Recommended → Conditionally required if not `http` and `network.protocol.version` is set | +| `net.protocol.version` → `network.protocol.version` | • Examples fixed: `2.0` → `2` and `3.0` → `3`
• See note if [migrating from <= v1.19.0](#migrating-from--v1190) | +| `net.sock.family` | Removed | +| `net.sock.peer.addr` → `network.peer.address` | On HTTP server spans: if `http.client_ip` was unknown, then also `net.sock.peer.addr` → `client.address`; `client.address` must be provided to sampler | +| `net.sock.peer.port` → `network.peer.port` | Now captured even if same as `server.port` | +| `net.sock.peer.name` | Removed | +| New: `http.request.method_original` | Only captured when `http.request.method` is `_OTHER` | +| New: `error.type` | | + + +References: + +- [Common attributes v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md#common-attributes) +- [Common attributes v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-spans.md#common-attributes) + +### HTTP client span attributes + + +| Change | Comments | +| --- | --- | +| `http.url` → `url.full` | | +| `http.resend_count` → `http.request.resend_count` | | +| `net.peer.name` → `server.address` | | +| `net.peer.port` → `server.port` | Now captured even when same as default port for scheme | + + +References: + +- [HTTP client span attributes v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md#http-client) +- [HTTP client span attributes v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-spans.md#metric-httpserverrequestduration) + +### HTTP server span attributes + + +| Change | Comments | +| --- | --- | +| `http.route` | No change | +| `http.target` → `url.path` and `url.query` | Split into two separate attributes | +| `http.scheme` → `url.scheme` | Now factors in [X-Forwarded-Proto][], [Forwarded#proto][] headers | +| `http.client_ip` → `client.address` | If `http.client_ip` was unknown (i.e., no [X-Forwarded-For][], [Forwarded#for][] headers), then `net.sock.peer.addr` → `client.address`; now must be provided to sampler | +| `net.host.name` → `server.address` | Now based only on [Host][Host header], [:authority][HTTP/2 authority], [X-Forwarded-Host][], [Forwarded#host][] headers | +| `net.host.port` → `server.port` | • Now based only on [Host][Host header], [:authority][HTTP/2 authority], [X-Forwarded-Host][X-Forwarded-Host], [Forwarded#host][] headers
• Now captured even when same as default port for scheme | +| `net.sock.host.addr` → `network.local.address` | | +| `net.sock.host.port` → `network.local.port` | No longer defaults to `server.port` when `network.local.address` is set. | + + +References: + +- [HTTP server span attributes v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md#http-server) +- [HTTP server span attributes v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-spans.md#metric-httpserverrequestduration) + +### HTTP client and server span names + +The `{http.method}` portion of span names is replace by `HTTP` when +`{http.method}` is `_OTHER`. + +See note if [migrating from `<= v1.17.0`](#migrating-from--v1170). + +References: + +- [HTTP client and server span names v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md#name) +- [HTTP client and server span names v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-spans.md#metric-httpserverrequestduration) + +### HTTP client duration metric + +Metric changes: + +- **Name**: `http.client.duration` → `http.client.request.duration` +- **Unit**: `ms` → `s` +- **Description**: `Measures the duration of inbound HTTP requests.` → + `Duration of HTTP server requests.` +- **Histogram buckets**: boundaries updated to reflect change from milliseconds + to seconds, and zero bucket boundary removed +- **Attributes**: see table below + + +| Attribute change | Comments | +| --- | --- | +| `http.method` → `http.request.method` | Now captures only 9 common HTTP methods by default plus `_OTHER` | +| `http.status_code` → `http.response.status_code` | | +| `net.peer.name` → `server.address` | | +| `net.peer.port` → `server.port` | Now captured even when same as default port for scheme | +| `net.sock.peer.addr` | Removed | +| `net.protocol.name` → `network.protocol.name` | Recommended → Conditionally required if not `http` and `network.protocol.version` is set | +| `net.protocol.version` → `network.protocol.version` | Examples fixed: `2.0` → `2` and `3.0` → `3`; see note if [migrating from `<= v1.19.0`](#migrating-from--v1190) | +| New: `error.type` | | + + +References: + +- [Metric `http.client.duration` v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md#metric-httpclientduration) +- [Metric `http.client.request.duration` v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-metrics.md#metric-httpserverrequestduration) + +### HTTP server duration metric + +Metric changes: + +- **Name**: `http.server.duration` → `http.server.request.duration` +- **Unit**: `ms` → `s` +- **Description**: `Measures the duration of inbound HTTP requests.` → + `Duration of HTTP server requests.` +- **Histogram buckets**: boundaries updated to reflect change from milliseconds + to seconds, and zero bucket boundary removed +- **Attributes**: see table below + + +| Attribute change | Comments | +| --- | --- | +| `http.route` | No change | +| `http.method` → `http.request.method` | Now captures only 9 common HTTP methods by default plus `_OTHER` | +| `http.status_code` → `http.response.status_code` | | +| `http.scheme` → `url.scheme` | Now factors in [`X-Forwarded-Proto` span][X-Forwarded-Proto], [`Forwarded#proto` span][Forwarded#proto] headers | +| `net.protocol.name` → `network.protocol.name` | Recommended → Conditionally required if not `http` and `network.protocol.version` is set | +| `net.protocol.version` → `network.protocol.version` | Examples fixed: `2.0` → `2` and `3.0` → `3`; see note if [migrating from `<= v1.19.0`](#migrating-from--v1190) | +| `net.host.name` → `server.address` | • Recommended → Opt-In (due to high-cardinality vulnerability since based on HTTP headers)
• Now based only on [`Host` span][Host header], [`:authority` span][HTTP/2 authority], [`X-Forwarded-Host` span][X-Forwarded-Host], [`Forwarded#host` span][Forwarded#host] headers | +| `net.host.port` → `server.port` | • Recommended → Opt-In (due to high-cardinality vulnerability since based on HTTP headers)
• Now based only on [`Host` span][Host header], [`:authority` span][HTTP/2 authority], [`X-Forwarded-Host` span][X-Forwarded-Host], [`Forwarded#host` span][Forwarded#host] headers | +| New: `error.type` | | + + +References: + +- [Metric `http.server.duration` v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md#metric-httpserverduration) +- [Metric `http.server.request.duration` v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-metrics.md#metric-httpserverrequestduration) + +## Migrating from a version prior to v1.20.0? + +In addition to the changes made to the HTTP semantic conventions +from +[v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) +to +[v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/README.md), +there are additional changes if you are migrating to v1.23.1 from a version prior to v1.20.0. + +### Migrating from `<= v1.19.0` + +- `http.flavor` → `network.protocol.version` + - Examples fixed: `2.0` → `2` and `3.0` → `3` + +### Migrating from `<= v1.18.0` + +- `http.user_agent` → `user_agent.original` + +### Migrating from `<= v1.17.0` + +#### HTTP server span name + +- When `http.route` is available:
`{http.route}` → + `{summary} {http.route}` +- When `http.route` is not available:
`HTTP {http.method}` → + `{summary}` + +Where `{summary}` is `{http.method}`, unless `{http.method}` is `_OTHER`, in +which case `{summary}` is `HTTP`. + +#### HTTP client span name + +- `HTTP {http.method}` → `{summary}` + +Where `{summary}` is `{http.method}`, unless `{http.method}` is `_OTHER`, in +which case `{summary}` is `HTTP`. + +### Migrating from `<= v1.16.0` + +This document does not cover these versions. + +[Host header]: https://tools.ietf.org/html/rfc7230#section-5.4 +[HTTP/2 authority]: https://tools.ietf.org/html/rfc9113#section-8.3.1 +[Forwarded#for]: +https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#for +[Forwarded#proto]: +https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto +[Forwarded#host]: +https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#host +[X-Forwarded-For]: +https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-For +[X-Forwarded-Proto]: +https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto +[X-Forwarded-Host]: +https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Host diff --git a/docs/http/reverse-proxy-http-server.png b/docs/http/reverse-proxy-http-server.png new file mode 100644 index 0000000000..1649e41255 Binary files /dev/null and b/docs/http/reverse-proxy-http-server.png differ diff --git a/docs/http/simple-http-server.png b/docs/http/simple-http-server.png new file mode 100644 index 0000000000..41d4a2574c Binary files /dev/null and b/docs/http/simple-http-server.png differ diff --git a/docs/messaging/README.md b/docs/messaging/README.md index e117836a2e..0d9e3b929c 100644 --- a/docs/messaging/README.md +++ b/docs/messaging/README.md @@ -1,7 +1,7 @@ @@ -14,11 +14,13 @@ This document defines semantic conventions for messaging systems spans, metrics Semantic conventions for messaging systems are defined for the following signals: * [Messaging Spans](messaging-spans.md): Semantic Conventions for messaging *spans*. +* [Messaging Metrics](messaging-metrics.md): Semantic Conventions for messaging *metrics*. Technology specific semantic conventions are defined for the following messaging systems: * [Kafka](kafka.md): Semantic Conventions for *Apache Kafka*. * [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*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md new file mode 100644 index 0000000000..eea9ae1f81 --- /dev/null +++ b/docs/messaging/azure-messaging.md @@ -0,0 +1,262 @@ + + +# Semantic Conventions for Azure Messaging systems + +**Status**: [Experimental][DocumentStatus] + +The Semantic Conventions for [Azure Service Bus](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-messaging-overview) and [Azure Event Hubs](https://learn.microsoft.com/azure/event-hubs/event-hubs-about) 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. + +## Azure Service Bus + +`messaging.system` MUST be set to `"servicebus"`. + +### Span attributes + +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.system`](/docs/attributes-registry/messaging.md) | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `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.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` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [6] | `MyQueue`; `MyTopic` | `Conditionally Required` [7] | ![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 [8] | `/customers/{customerId}` | `Conditionally Required` [9] | ![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` [10] | ![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.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` [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.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.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.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` | ![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) | +| [`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) | +| [`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.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. + +**[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]:** 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 value is `true`. When missing, the value is assumed to be `false`. + +**[6]:** 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. + +**[7]:** If span describes operation on a single message or if the value applies to all messages in the batch. + +**[8]:** 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]:** If available. Instrumentations MUST NOT use `messaging.destination.name` as template unless low-cardinality of destination name is guaranteed. + +**[10]:** If value is `true`. When missing, the value is assumed to be `false`. + +**[11]:** If delivery count is available and is bigger than 0. + +**[12]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. + +**[13]:** 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 +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. +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. + +`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 | +|---|---|---| +| `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) | +| `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) | +| `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) | +| `process` | One or more messages are delivered to or processed by a consumer. | ![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 | +|---|---|---| +| `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) | +| `servicebus` | Azure Service Bus | ![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) | +| `rabbitmq` | RabbitMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rocketmq` | Apache RocketMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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.servicebus.disposition_status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `complete` | Message is completed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `abandon` | Message is abandoned | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dead_letter` | Message is sent to dead letter queue | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `defer` | Message is deferred | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +## Azure Event Hubs + +`messaging.system` MUST be set to `"eventhubs"`. + +### Span attributes + +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.system`](/docs/attributes-registry/messaging.md) | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `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.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` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [6] | `MyQueue`; `MyTopic` | `Conditionally Required` [7] | ![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.destination.template`](/docs/attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [8] | `/customers/{customerId}` | `Conditionally Required` [9] | ![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` [10] | ![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. [11] | `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.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.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. [12] | `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. [13] | `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` | ![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` [14] | ![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. [15] | `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. [16] | `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. + +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]:** 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 value is `true`. When missing, the value is assumed to be `false`. + +**[6]:** 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. + +**[7]:** If span describes operation on a single message or if the value applies to all messages in the batch. + +**[8]:** 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]:** If available. Instrumentations MUST NOT use `messaging.destination.name` as template unless low-cardinality of destination name is guaranteed. + +**[10]:** If value is `true`. When missing, the value is assumed to be `false`. + +**[11]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. + +**[12]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed +body size should be used. + +**[13]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed +size should be used. + +**[14]:** If the operation is not sufficiently described by `messaging.operation.type`. + +**[15]:** Semantic conventions for individual messaging systems SHOULD document whether `network.peer.*` attributes are applicable. +Network peer address and port are important when the application interacts with individual intermediary nodes directly, +If a messaging operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. + +**[16]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +`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 | +|---|---|---| +| `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) | +| `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) | +| `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) | +| `process` | One or more messages are delivered to or processed by a consumer. | ![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 | +|---|---|---| +| `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) | +| `servicebus` | Azure Service Bus | ![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) | +| `rabbitmq` | RabbitMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rocketmq` | Apache RocketMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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) | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md new file mode 100644 index 0000000000..5707da5b31 --- /dev/null +++ b/docs/messaging/gcp-pubsub.md @@ -0,0 +1,137 @@ + + +# Semantic Conventions for Google Cloud Pub/Sub + +**Status**: [Experimental][DocumentStatus] + +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"`. + +## Span attributes + +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.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) | +| [`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) | + + +## 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 + +Given is a process P that asynchronously publishes 2 messages in a batch to a topic T on Pub/Sub. + +```mermaid +flowchart LR; + subgraph PRODUCER + direction LR + CA[Span Create A] + CB[Span Create B] + P[Span Publish A B] + end + CA-. link .-P; + CB-. link .-P; + + classDef producer fill:green + class P,CA,CB producer + classDef normal fill:green + class PA,PB,D1 normal + linkStyle 0,1 color:green,stroke:green +``` + +| Field or Attribute | Span Create A | Span Create B | Span Publish A B | +|-|-|-|-| +| Span name | `T create` | `T create` | `publish` | +| 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.type` | `"create"` | `"create"` | `"publish"` | +| `messaging.message.id` | `"a1"` | `"a2"` | | +| `messaging.message.envelope.size` | `1` | `1` | | +| `messaging.system` | `"gcp_pubsub"` | `"gcp_pubsub"` | `"gcp_pubsub"` | + +### Unary Pull Example + +```mermaid +flowchart TD; + subgraph CONSUMER + direction LR + R1[Receive m1] + SM1[Ack m1] + EM1[Modack m1] + end + subgraph PRODUCER + direction LR + CM1[Create m1] + PM1[Publish] + end + %% Link 0 + CM1-. link .-PM1; + %% Link 1 + CM1-. link .-R1; + %% Link 2 + R1-. link .-SM1; + %% Link 3 + R1-. link .-EM1; + + %% Style the node and corresponding link + %% Producer links and nodes + classDef producer fill:green + class PM1,CM1 producer + linkStyle 0 color:green,stroke:green + + %% Consumer links and nodes + classDef consumer fill:#49fcdc + class R1 consumer + linkStyle 1 color:#49fcdc,stroke:#49fcdc + + classDef ack fill:#577eb5 + class SM1 ack + linkStyle 2 color:#577eb5,stroke:#577eb5 + + classDef modack fill:#0560f2 + class EM1 modack + linkStyle 3 color:#0560f2,stroke:#0560f2 +``` + +| 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` | +| 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.message.id` | `"a1"` | | `"a1"` | | | +| `messaging.message.envelope.size` | `1` | `1` | `1` | | | +| `messaging.gcp_pubsub.message.ack_id` | | | | `"ack_id1"` |`"ack_id1"` | +| `messaging.gcp_pubsub.message.delivery_attempt` | | | | `0` | | +| `messaging.gcp_pubsub.message.ack_deadline` | | | | | `0` | + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index 47d36bb22f..e53472a28f 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -10,11 +10,7 @@ linkTitle: Kafka - [Span attributes](#span-attributes) - [Examples](#examples) - * [Apache Kafka with Quarkus or Spring Boot Example](#apache-kafka-with-quarkus-or-spring-boot-example) -- [Metrics](#metrics) - * [General Metrics](#general-metrics) - * [Producer Metrics](#producer-metrics) - * [Consumer Metrics](#consumer-metrics) + - [Apache Kafka with Quarkus or Spring Boot Example](#apache-kafka-with-quarkus-or-spring-boot-example) @@ -28,18 +24,18 @@ described on this page. For Apache Kafka, the following additional attributes are defined: - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `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. [1] | `myKey` | Recommended | -| `messaging.kafka.consumer.group` | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | Recommended | -| `messaging.kafka.destination.partition` | int | Partition the message is sent to. | `2` | Recommended | -| `messaging.kafka.message.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | Recommended | -| `messaging.kafka.message.tombstone` | boolean | A boolean that is true if the message is a tombstone. | | Conditionally Required: [2] | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`messaging.kafka.message.tombstone`](/docs/attributes-registry/messaging.md) | boolean | A boolean that is true if the message is a tombstone. | | `Conditionally Required` [1] | ![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. [2] | `myKey` | `Recommended` | ![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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** 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. +**[1]:** If value is `true`. When missing, the value is assumed to be `false`. -**[2]:** If value is `true`. When missing, the value is assumed to be `false`. +**[2]:** 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. For Apache Kafka producers, [`peer.service`](/docs/general/attributes.md#general-remote-service-attributes) SHOULD be set to the name of the broker or service the message will be sent to. @@ -57,7 +53,7 @@ One process, CA, receives the message and publishes a new message to a topic T2 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` to `receive`, +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. ``` @@ -81,82 +77,11 @@ Process CB: | Span Rcv2 | | `service.name` | | `"myConsumer1"` | `"myConsumer1"` | | `"myConsumer2"` | | `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | | `messaging.destination.name` | `"T1"` | `"T1"` | `"T1"` | `"T2"` | `"T2"` | -| `messaging.operation` | | | `"process"` | | `"receive"` | +| `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.partition` | `"1"` | `"1"` | `"1"` | `"3"` | `"3"` | +| `messaging.kafka.destination.partition` | `"1"` | `"1"` | `"1"` | `"3"` | `"3"` | | `messaging.kafka.message.offset` | `"12"` | `"12"` | `"12"` | `"32"` | `"32"` | -## Metrics - -This section defines how to apply semantic conventions when collecting Kafka metrics. - -### General Metrics - -**Description:** General Kafka metrics. - -| Name | Instrument | Value type | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | Attribute Key | Attribute Values | -| ---------------------------------------------| ------------- | ---------- | ------ | -------------------------------------------- | -------------- | ------------- | ---------------- | -| messaging.kafka.messages | Counter | Int64 | messages | `{message}` | The number of messages received by the broker. | | | -| messaging.kafka.requests.failed | Counter | Int64 | requests | `{request}` | The number of requests to the broker resulting in a failure. | `type` | `produce`, `fetch` | -| messaging.kafka.requests.queue | UpDownCounter | Int64 | requests | `{request}` | The number of requests in the request queue. | | | -| messaging.kafka.network.io | Counter | Int64 | bytes | `By` | The bytes received or sent by the broker. | `state` | `in`, `out` | -| messaging.kafka.purgatory.size | UpDownCounter | Int64 | requests | `{request}` | The number of requests waiting in the purgatory. | `type` | `produce`, `fetch` | -| messaging.kafka.partitions.all | UpDownCounter | Int64 | partitions | `{partition}` | The number of partitions in the broker. | | | -| messaging.kafka.partitions.offline | UpDownCounter | Int64 | partitions | `{partition}` | The number of offline partitions. | | | -| messaging.kafka.partitions.under-replicated | UpDownCounter | Int64 | partition | `{partition}` | The number of under replicated partitions. | | | -| messaging.kafka.isr.operations | Counter | Int64 | operations | `{operation}` | The number of in-sync replica shrink and expand operations. | `operation` | `shrink`, `expand` | -| messaging.kafka.lag_max | Gauge | Int64 | lag max | `{message}` | Max lag in messages between follower and leader replicas. | | | -| messaging.kafka.controllers.active | UpDownCounter | Int64 | controllers | `{controller}` | The number of active controllers in the broker. | | | -| messaging.kafka.leader.elections | Counter | Int64 | elections | `{election}` | Leader election rate (increasing values indicates broker failures). | | | -| messaging.kafka.leader.unclean-elections | Counter | Int64 | elections | `{election}` | Unclean leader election rate (increasing values indicates broker failures). | | | -| messaging.kafka.brokers | UpDownCounter | Int64 | brokers | `{broker}` | Number of brokers in the cluster. | | | -| messaging.kafka.topic.partitions | UpDownCounter | Int64 | partitions | `{partition}` | Number of partitions in topic. | `topic` | The ID (integer) of a topic | -| messaging.kafka.partition.current_offset | Gauge | Int64 | partition offset | `{partition offset}` | Current offset of partition of topic. | `topic` | The ID (integer) of a topic | -| | | | | | | `partition` | The number (integer) of the partition | -| messaging.kafka.partition.oldest_offset | Gauge | Int64 | partition offset | `{partition offset}` | Oldest offset of partition of topic | `topic` | The ID (integer) of a topic | -| | | | | | | `partition` | The number (integer) of the partition | -| messaging.kafka.partition.replicas.all | UpDownCounter | Int64 | replicas | `{replica}` | Number of replicas for partition of topic | `topic` | The ID (integer) of a topic | -| | | | | | | `partition` | The number (integer) of the partition | -| messaging.kafka.partition.replicas.in_sync | UpDownCounter | Int64 | replicas | `{replica}` | Number of synchronized replicas of partition | `topic` | The ID (integer) of a topic | -| | | | | | | `partition` | The number (integer) of the partition| - -### Producer Metrics - -**Description:** Kafka Producer level metrics. - -| Name | Instrument | Value type | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | Attribute Key | Attribute Values | -| --------------------------------------------- | ------------- | ---------- | ------ | -------------------------------------------- | -------------- | ------------- | ---------------- | -| messaging.kafka.producer.outgoing-bytes.rate | Gauge | Double | bytes per second | `By/s` | The average number of outgoing bytes sent per second to all servers. | `client-id` | `client-id` value | -| messaging.kafka.producer.responses.rate | Gauge | Double | responses per second | `{response}/s` | The average number of responses received per second. | `client-id` | `client-id` value | -| messaging.kafka.producer.bytes.rate | Gauge | Double | bytes per second | `By/s` | The average number of bytes sent per second for a specific topic. | `client-id` | `client-id` value | -| | | | | | | `topic` | topic name | -| messaging.kafka.producer.compression-ratio | Gauge | Double | compression ratio | `{compression}` | The average compression ratio of record batches for a specific topic. | `client-id` | `client-id` value | -| | | | | | | `topic` | topic name | -| messaging.kafka.producer.record-error.rate | Gauge | Double | error rate | `{error}/s` | The average per-second number of record sends that resulted in errors for a specific topic. | `client-id` | `client-id` value | -| | | | | | | `topic` | topic name | -| messaging.kafka.producer.record-retry.rate | Gauge | Double | retry rate | `{retry}/s` | The average per-second number of retried record sends for a specific topic. | `client-id` | `client-id` value | -| | | | | | | `topic` | topic name | -| messaging.kafka.producer.record-sent.rate | Gauge | Double | records sent rate | `{record_sent}/s` | The average number of records sent per second for a specific topic. | `client-id` | `client-id` value | -| | | | | | | `topic` | topic name | - -### Consumer Metrics - -**Description:** Kafka Consumer level metrics. - -| Name | Instrument | Value type | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | Attribute Key | Attribute Values | -| --------------------------------------------- | ------------- | ---------- | ------ | -------------------------------------------- | -------------- | ------------- | ---------------- | -| messaging.kafka.consumer.members | UpDownCounter | Int64 | members | `{member}` | Count of members in the consumer group | `group` | The ID (string) of a consumer group | -| messaging.kafka.consumer.offset | Gauge | Int64 | offset | `{offset}` | Current offset of the consumer group at partition of topic | `group` | The ID (string) of a consumer group | -| | | | | | | `topic` | The ID (integer) of a topic | -| | | | | | | `partition` | The number (integer) of the partition | -| messaging.kafka.consumer.offset_sum | Gauge | Int64 | offset sum | `{offset sum}` | Sum of consumer group offset across partitions of topic | `group` | The ID (string) of a consumer group | -| | | | | | | `topic` | The ID (integer) of a topic | -| messaging.kafka.consumer.lag | Gauge | Int64 | lag | `{lag}` | Current approximate lag of consumer group at partition of topic | `group` | The ID (string) of a consumer group | -| | | | | | | `topic` | The ID (integer) of a topic | -| | | | | | | `partition` | The number (integer) of the partition | -| messaging.kafka.consumer.lag_sum | Gauge | Int64 | lag sum | `{lag sum}` | Current approximate sum of consumer group lag across all partitions of topic | `group` | The ID (string) of a consumer group | -| | | | | | | `topic` | The ID (integer) of a topic | - -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md new file mode 100644 index 0000000000..43f91ff657 --- /dev/null +++ b/docs/messaging/messaging-metrics.md @@ -0,0 +1,187 @@ +# Semantic Conventions for Messaging Metrics + +**Status**: [Experimental][DocumentStatus] + + + + + +- [Common attributes](#common-attributes) +- [Producer metrics](#producer-metrics) + - [Metric: `messaging.publish.duration`](#metric-messagingpublishduration) + - [Metric: `messaging.publish.messages`](#metric-messagingpublishmessages) +- [Consumer metrics](#consumer-metrics) + - [Metric: `messaging.receive.duration`](#metric-messagingreceiveduration) + - [Metric: `messaging.receive.messages`](#metric-messagingreceivemessages) + - [Metric: `messaging.process.duration`](#metric-messagingprocessduration) + - [Metric: `messaging.process.messages`](#metric-messagingprocessmessages) + + + +> **Warning** +> Existing messaging instrumentations that are using +> [v1.24.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/messaging/messaging-metrics.md) +> (or prior) SHOULD NOT change the version of the messaging conventions that they emit +> 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 + +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.system`](/docs/attributes-registry/messaging.md) | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `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. [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.destination.template`](/docs/attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [4] | `/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. [5] | `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. [6] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[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. + +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. + +**[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. + +**[3]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. + +**[4]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. + +**[5]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. + +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +`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) | +| `servicebus` | Azure Service Bus | ![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) | +| `rabbitmq` | RabbitMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rocketmq` | Apache RocketMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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) | + + +## Producer metrics + +### Metric: `messaging.publish.duration` + +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.31.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.publish.duration` | Histogram | `s` | Measures the duration of publish operation. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### 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) | + + +> 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.31.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 ]`. + +When this metric is reported alongside a messaging receive span, the metric value SHOULD be the same as the corresponding span duration. + + +| 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) | + + +### 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) | + + +### 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 SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.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.process.duration` | Histogram | `s` | Measures the duration of process operation. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### 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) | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[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 cee92e4815..d8246af684 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -1,4 +1,4 @@ -# Messaging Systems +# Semantic Conventions for Messaging Spans **Status**: [Experimental][DocumentStatus] @@ -7,56 +7,40 @@ - [Definitions](#definitions) - * [Message](#message) - * [Producer](#producer) - * [Consumer](#consumer) - * [Intermediary](#intermediary) - * [Destinations](#destinations) - * [Message consumption](#message-consumption) - * [Conversations](#conversations) - * [Temporary and anonymous destinations](#temporary-and-anonymous-destinations) + - [Message](#message) + - [Producer](#producer) + - [Consumer](#consumer) + - [Intermediary](#intermediary) + - [Destinations](#destinations) + - [Message consumption](#message-consumption) + - [Conversations](#conversations) + - [Temporary and anonymous destinations](#temporary-and-anonymous-destinations) - [Conventions](#conventions) - * [Context propagation](#context-propagation) - * [Span name](#span-name) - * [Span kind](#span-kind) - * [Operation names](#operation-names) + - [Context propagation](#context-propagation) + - [Span name](#span-name) + - [Operation types](#operation-types) + - [Span kind](#span-kind) + - [Trace structure](#trace-structure) + - [Producer spans](#producer-spans) + - [Consumer spans](#consumer-spans) - [Messaging attributes](#messaging-attributes) - * [Attribute namespaces](#attribute-namespaces) - * [Consumer attributes](#consumer-attributes) - * [Per-message attributes](#per-message-attributes) - * [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems) + - [Consumer attributes](#consumer-attributes) + - [Per-message attributes](#per-message-attributes) + - [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems) - [Examples](#examples) - * [Topic with multiple consumers](#topic-with-multiple-consumers) - * [Batch receiving](#batch-receiving) - * [Batch processing](#batch-processing) + - [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) > **Warning** -> Existing Messaging instrumentations that are using -> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/messaging.md) -> (or prior): -> -> * SHOULD NOT change the version of the networking attributes that they emit -> until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in Messaging instrumentations). -> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` -> in the existing major version which is a comma-separated list of values. -> The only values defined so far are: -> * `http` - emit the new, stable networking attributes, -> and stop emitting the old experimental networking attributes -> that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable networking attributes, -> allowing for a seamless transition. -> * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental networking attributes -> the instrumentation was emitting previously. -> * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). +> Existing messaging instrumentations that are using +> [v1.24.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/messaging/messaging-spans.md) +> (or prior) SHOULD NOT change the version of the messaging conventions that they emit +> 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. ## Definitions @@ -64,7 +48,7 @@ Although messaging systems are not as standardized as, e.g., HTTP, it is assumed that the following definitions are applicable to most of them that have similar concepts at all (names borrowed mostly from JMS): -A *message* is an envelope with a potentially empty payload. +A *message* is an envelope with a potentially empty body. This envelope may offer the possibility to convey additional metadata, often in key/value form. A message is sent by a message *producer* to: @@ -105,6 +89,12 @@ A destination is usually uniquely identified by its name within the messaging system instance. Examples of a destination name would be an URL or a simple one-word identifier. +In some use cases, messages are routed within one or multiple brokers. In such +cases, the destination the message was originally published to is different +from the destination it is being consumed from. When information about the +destination where the message was originally published to is available, consumers +can record them under the `destination_publish` namespace. + Typical examples of destinations include Kafka topics, RabbitMQ queues and topics. ### Message consumption @@ -163,154 +153,273 @@ 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 operation being performed in the following format: +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: ``` ``` -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.22.0/specification/trace/api.md#span)). +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: + +``` + +``` + +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.31.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. -The values allowed for `` are defined in the section [Operation names](#operation-names) below. -If the format above is used, the operation name MUST match the `messaging.operation` attribute defined for message consumer spans below. - Examples: * `shop.orders publish` -* `shop.orders receive` -* `shop.orders process` +* `shop.orders subscribe` +* `shop.orders settle` * `print_jobs publish` +* `print_jobs nack` * `topic with spaces process` -* `AuthenticationRequest-Conversations process` -* `(anonymous) publish` (`(anonymous)` being a stable identifier for an unnamed destination) +* `AuthenticationRequest-Conversations settle` +* `(anonymous) send` (`(anonymous)` being a stable identifier for an unnamed destination) -### Span kind +Messaging system specific adaptions to span naming MUST be documented in [semantic conventions for specific messaging technologies](#semantic-conventions-for-specific-messaging-technologies). -A producer of a message should set the span kind to `PRODUCER` unless it synchronously waits for a response: then it should use `CLIENT`. -The processor of the message should set the kind to `CONSUMER`, unless it always sends back a reply that is directed to the producer of the message -(as opposed to e.g., a queue on which the producer happens to listen): then it should use `SERVER`. +### Operation types -### Operation names +The following operation types related to messages are defined for these semantic conventions: -The following operations related to messages are defined for these semantic conventions: - -| Operation name | Description | +| Operation type | Description | | -------------- | ----------- | -| `publish` | A message is sent to a destination by a message producer/client. | -| `receive` | A message is received from a destination by a message consumer/server. | -| `process` | A message that was previously received from a destination is processed by a message consumer/server. | +| `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. | +| `settle` | One or more messages are settled. | + +### Span kind + +[Span kinds](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/trace/api.md#spankind) +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. | + +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.31.0/specification/trace/api.md#spankind), +e. g. it should be set to CLIENT for the "Publish" span if its context is not +used as creation context and if the "Publish" span models a synchronous call to +the intermediary. + +Setting span kinds according to this table ensures that span links between +consumers and producers always exist between a PRODUCER span on the producer +side and a CONSUMER span on the consumer side. This allows analysis tools to +interpret linked traces without the need for additional semantic hints. + +### Trace structure + +#### Producer spans + +"Create" spans MAY be created when a message is created or passed to the client +library or other component responsible for publishing. A single "Create" span +SHOULD account only for a single message. "Publish" spans SHOULD be created +for operations of sending or publishing a message to an intermediary. A single +"Publish" span can account for a single message, or for multiple messages (in +the case of sending messages in batches). + +If a user provides a custom creation context in a message, this context SHOULD +NOT be modified and a "Create" span SHOULD NOT be created. Otherwise, if a +"Create" span exists for a message, its context SHOULD be injected into the +message. If no "Create" span exists and no custom creation context is injected +into the message, the context of the related "Publish" span SHOULD be injected +into the message. + +The "Publish" span SHOULD always link to the creation context that was injected +into a message either from a "Create" span or as a custom creation context. + +#### Consumer spans + +"Receive" spans SHOULD be created for operations of passing messages to the +application when those operations are initiated by the application code +(pull-based scenarios). + +"Process" spans SHOULD be created for operations of passing messages to the +application when those operations are not initiated by the application code +(push-based scenarios). Such "Process" span covers the duration of such an +operation, which is usually a callback or handler. + +"Process" spans MAY be created in addition to "Receive" spans for pull-based +scenarios for operations of processing messages. Such spans could be created by +application code, or by abstraction layers built on top of messaging SDKs. + +"Receive" or "Process" spans MUST NOT be created for messages that are +pre-fetched or cached by messaging libraries or SDKs until they are forwarded +to the caller. + +A single "Process" or "Receive" span can account for a single message, for a +batch of messages, or for no message at all (if it is signalled that no +messages were received). For each message it accounts for, the "Process" or +"Receive" span SHOULD link to the message's creation context. + +"Settle" spans SHOULD be created for every manually or automatically triggered +settlement operation. A single "Settle" span can account for a single message +or for multiple messages (in case messages are passed for settling as batches). +For each message it accounts for, the "Settle" span MAY link to the creation +context of the message. ## Messaging attributes - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required | -| `messaging.operation` | string | A string identifying the kind of messaging operation as defined in the [Operation names](#operation-names) section above. [1] | `publish` | Required | -| `messaging.batch.message_count` | int | The number of messages sent, received, or processed in the scope of the batching operation. [2] | `0`; `1`; `2` | Conditionally Required: [3] | -| `messaging.client_id` | 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 | -| `messaging.destination.anonymous` | boolean | A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name). | | Conditionally Required: [4] | -| `messaging.destination.name` | string | The message destination name [5] | `MyQueue`; `MyTopic` | Conditionally Required: [6] | -| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [7] | `/customers/{customerId}` | Conditionally Required: [8] | -| `messaging.destination.temporary` | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | Conditionally Required: [9] | -| `messaging.message.conversation_id` | string | The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended: [10] | -| `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [11] | -| `messaging.message.payload_compressed_size_bytes` | int | The compressed size of the message payload in bytes. | `2048` | Recommended: [12] | -| `messaging.message.payload_size_bytes` | int | The (uncompressed) size of the message payload in bytes. Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. | `2738` | Recommended: [13] | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [14] | `3.1.1` | Recommended | -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. [15] | `example.com` | Conditionally Required: If available. | -| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | -| [`server.socket.domain`](../general/attributes.md) | string | The domain name of an immediate peer. [16] | `proxy.example.com` | Recommended: [17] | -| [`server.socket.port`](../general/attributes.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | +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.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). + + +| 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 | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `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.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` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [6] | `MyQueue`; `MyTopic` | `Conditionally Required` [7] | ![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 [8] | `/customers/{customerId}` | `Conditionally Required` [9] | ![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` [10] | ![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. [11] | `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.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. [12] | `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. [13] | `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` | ![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` [14] | ![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. [15] | `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. [16] | `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]:** 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]:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. -**[3]:** If the span describes an operation on a batch of messages. +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. -**[4]:** If value is `true`. When missing, the value is assumed to be `false`. +Instrumentations SHOULD document the list of errors they report. -**[5]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If -the broker does not have such notion, the destination name SHOULD uniquely identify the broker. +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. -**[6]:** If span describes operation on a single message or if the value applies to all messages in the batch. +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[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. +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), +it's RECOMMENDED to: -**[8]:** If available. Instrumentations MUST NOT use `messaging.destination.name` as template unless low-cardinality of destination name is guaranteed. +* 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. -**[9]:** If value is `true`. When missing, the value is assumed to be `false`. +**[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. -**[10]:** Only if span represents operation on a single message. +**[4]:** If the span describes an operation on a batch of messages. -**[11]:** Only for spans that represent an operation on a single message. +**[5]:** If value is `true`. When missing, the value is assumed to be `false`. -**[12]:** Only if span represents operation on a single message. +**[6]:** 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. -**[13]:** Only if span represents operation on a single message. +**[7]:** If span describes operation on a single message or if the value applies to all messages in the batch. -**[14]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[8]:** 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. -**[15]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. +**[9]:** If available. Instrumentations MUST NOT use `messaging.destination.name` as template unless low-cardinality of destination name is guaranteed. -**[16]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. +**[10]:** If value is `true`. When missing, the value is assumed to be `false`. -**[17]:** If different than `server.address` and if `server.socket.address` is set. +**[11]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. -`messaging.operation` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +**[12]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed +body size should be used. -| Value | Description | -|---|---| -| `publish` | publish | -| `receive` | receive | -| `process` | process | - +**[13]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed +size should be used. -Additionally `server.port` from the [network attributes][] is recommended. -Furthermore, it is strongly recommended to add the [`network.transport`][] attribute and follow its guidelines, especially for in-process queueing systems (like [Hangfire][], for example). -These attributes should be set to the broker to which the message is sent/from which it is received. +**[14]:** If the operation is not sufficiently described by `messaging.operation.type`. -### Attribute namespaces +**[15]:** 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. -- `messaging.message`: Contains attributes that describe individual messages -- `messaging.destination`: Contains attributes that describe the logical entity - messages are published to and received from. - See [Destinations](#destinations) for more details -- `messaging.batch`: Contains attributes that describe batch operations -- `messaging.consumer`: Contains attributes that describe application instance that consumes a message. See [consumer](#consumer) for more details +**[16]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -Communication with broker is described with general [network attributes]. +`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. -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). +| Value | Description | Stability | +|---|---|---| +| `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) | +| `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) | +| `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) | +| `process` | One or more messages are delivered to or processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `settle` | One or more messages are settled. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -[network attributes]: /docs/general/attributes.md#server-and-client-attributes -[`network.transport`]: /docs/general/attributes.md#network-attributes -[Hangfire]: https://www.hangfire.io/ +`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) | +| `servicebus` | Azure Service Bus | ![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) | +| `rabbitmq` | RabbitMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rocketmq` | Apache RocketMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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) | + ### Consumer attributes -The *receive* span is used to track the time used for receiving the message(s), whereas the *process* span(s) track the time for processing the message(s). -Note that one or multiple Spans with `messaging.operation` = `process` may often be the children of a Span with `messaging.operation` = `receive`. -The distinction between receiving and processing of messages is not always of particular interest or sometimes hidden away in a framework (see the [Message consumption](#message-consumption) section above) and therefore the attribute can be left out. -For batch receiving and processing (see the [Batch receiving](#batch-receiving) and [Batch processing](#batch-processing) examples below) in particular, the attribute SHOULD be set. -Even though in that case one might think that the processing span's kind should be `INTERNAL`, that kind MUST NOT be used. -Instead span kind should be set to either `CONSUMER` or `SERVER` according to the rules defined above. +The following additional attributes describe message consumer operations. + +Since messages could be routed by brokers, the destination messages are published +to may not match with the destination they are consumed from. + +If information about the original destination is available on the consumer, +consumer instrumentations SHOULD populate the attributes +under the namespace `messaging.destination_publish.*` + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`messaging.destination_publish.anonymous`](/docs/attributes-registry/messaging.md) | boolean | A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name). | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.destination_publish.name`](/docs/attributes-registry/messaging.md) | string | The name of the original destination the message was published to [1] | `MyQueue`; `MyTopic` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** 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. + ### Per-message attributes 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 MAY be set on links. See [Batch Receiving](#batch-receiving) and [Batch Processing](#batch-processing) for more information on correlation using links. +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. @@ -326,94 +435,136 @@ All attributes that are specific for a messaging system SHOULD be populated in ` ## Examples -### Topic with multiple consumers +This section contains a list of examples illustrating the use of the +conventions outlined above. Green boxes denote spans that are required to exist +in order to conform to those conventions. Other boxes denote spans that are not +required and covered by the conventions, but are hopefully helpful in +understanding how messaging spans can be integrated into an overall trace flow. +Solid arrows denote parent/child relationships, dotted arrows denote link +relationships. -Given is a process P, that publishes a message to a topic T on messaging system MS, and two processes CA and CB, which both receive the message and process it. +### Topic with multiple consumers -``` -Process P: | Span Prod1 | --- -Process CA: | Span CA1 | --- -Process CB: | Span CB1 | +Given is a publisher that publishes a message to a topic exchange "T" on RabbitMQ, and two consumers which both get the message delivered. + +```mermaid +flowchart LR; + subgraph PRODUCER + direction TB + P[Span Publish A] + end + subgraph CONSUMER1 + direction TB + R1[Span Process A 1] + end + subgraph CONSUMER2 + direction TB + R2[Span Process A 2] + end + P-. link .-R1; + P-. link .-R2; + + classDef normal fill:green + class P,R1,R2 normal + linkStyle 0,1 color:green,stroke:green ``` -| Field or Attribute | Span Prod1 | Span CA1 | Span CB1 | +| Field or Attribute | Span Publish A | Span Process A 1| Span Process A 2 | |-|-|-|-| -| Span name | `"T publish"` | `"T process"` | `"T process"` | -| Parent | | Span Prod1 | Span Prod1 | -| Links | | | | +| Span name | `T publish` | `T process` | `T process` | +| Parent | | | | +| Links | | `T publish` | `T publish` | | SpanKind | `PRODUCER` | `CONSUMER` | `CONSUMER` | -| Status | `Ok` | `Ok` | `Ok` | | `server.address` | `"ms"` | `"ms"` | `"ms"` | | `server.port` | `1234` | `1234` | `1234` | | `messaging.system` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` | | `messaging.destination.name` | `"T"` | `"T"` | `"T"` | -| `messaging.operation` | | `"process"` | `"process"` | -| `messaging.message.id` | `"a1"` | `"a1"`| `"a1"` | +| `messaging.operation.type` | `"publish"` | `"process"` | `"process"` | +| `messaging.message.id` | `"a"` | `"a"`| `"a"` | ### Batch receiving -Given is a process P, that publishes two messages to a queue Q on messaging system MS, and a process C, which receives both of them in one batch (Span Recv1) and processes each message separately (Spans Proc1 and Proc2). - -Since a span can only have one parent and the propagated trace and span IDs are not known when the receiving span is started, the receiving span will have no parent and the processing spans are correlated with the producing spans using links. - -``` -Process P: | Span Prod1 | Span Prod2 | --- -Process C: | Span Recv1 | - | Span Proc1 | - | Span Proc2 | +Given is a publisher that publishes two messages to a topic "Q" on Kafka, and a consumer which receives both messages in one batch. + +```mermaid +flowchart LR; + subgraph PRODUCER + direction TB + PA[Span Publish A] + PB[Span Publish B] + end + subgraph CONSUMER1 + direction TB + D1[Span Receive A B] + end + PA-. link .-D1; + PB-. link .-D1; + + classDef normal fill:green + class PA,PB,D1 normal + linkStyle 0,1 color:green,stroke:green ``` -| Field or Attribute | Span Prod1 | Span Prod2 | Span Recv1 | Span Proc1 | Span Proc2 | -|-|-|-|-|-|-| -| Span name | `"Q publish"` | `"Q publish"` | `"Q receive"` | `"Q process"` | `"Q process"` | -| Parent | | | | Span Recv1 | Span Recv1 | -| Links | | | | Span Prod1 | Span Prod2 | -| SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` | `CONSUMER` | `CONSUMER` | -| Status | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` | -| `server.address` | `"ms"` | `"ms"` | `"ms"` | `"ms"` | `"ms"` | -| `server.port` | `1234` | `1234` | `1234` | `1234` | `1234` | -| `messaging.system` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` | -| `messaging.destination.name` | `"Q"` | `"Q"` | `"Q"` | `"Q"` | `"Q"` | -| `messaging.operation` | | | `"receive"` | `"process"` | `"process"` | -| `messaging.message.id` | `"a1"` | `"a2"` | | `"a1"` | `"a2"` | -| `messaging.batch.message_count` | | | 2 | | | - -### Batch processing - -Given is a process P, that publishes two messages to a queue Q on messaging system MS, and a process C, which receives them separately in two different operations (Span Recv1 and Recv2) and processes both messages in one batch (Span Proc1). - -Since each span can only have one parent, C3 should not choose a random parent out of C1 and C2, but rather rely on the implicitly selected parent as defined by the [tracing API spec](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md). -Depending on the implementation, the producing spans might still be available in the meta data of the messages and should be added to C3 as links. -The client library or application could also add the receiver span's SpanContext to the data structure it returns for each message. In this case, C3 could also add links to the receiver spans C1 and C2. - -The status of the batch processing span is selected by the application. Depending on the semantics of the operation. A span status `Ok` could, for example, be set only if all messages or if just at least one were properly processed. - -``` -Process P: | Span Prod1 | Span Prod2 | --- -Process C: | Span Recv1 | Span Recv2 | - | Span Proc1 | +| Field or Attribute | Span Publish A | Span Publish B | Span Receive A B | +|-|-|-|-| +| Span name | `Q publish` | `Q publish` | `Q receive` | +| Parent | | | | +| Links | | | Span Publish A, Span Publish B | +| Link attributes | | | Span Publish A: `messaging.message.id`: `"a1"` | +| | | | Span Publish B: `messaging.message.id`: `"a2"` | +| SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` | +| `server.address` | `"ms"` | `"ms"` | `"ms"` | +| `server.port` | `1234` | `1234` | `1234` | +| `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | +| `messaging.destination.name` | `"Q"` | `"Q"` | `"Q"` | +| `messaging.operation.type` | `"publish"` | `"publish"` | `"receive"` | +| `messaging.message.id` | `"a1"` | `"a2"` | | +| `messaging.batch.message_count` | | | 2 | + +### Batch publishing + +Given is a publisher that publishes a batch with two messages to a topic "Q" on +Kafka, and two different consumers receiving one of the messages. + +```mermaid +flowchart LR; + subgraph PRODUCER + direction TB + CA[Span Create A] + CB[Span Create B] + P[Span Publish] + end + subgraph CONSUMER1 + direction TB + D1[Span Receive A] + end + subgraph CONSUMER2 + direction TB + D2[Span Receive B] + end + CA-. link .-P; + CB-. link .-P; + CA-. link .-D1; + CB-. link .-D2; + + classDef normal fill:green + class P,CA,CB,D1,D2 normal + linkStyle 0,1,2,3 color:green,stroke:green ``` -| Field or Attribute | Span Prod1 | Span Prod2 | Span Recv1 | Span Recv2 | Span Proc1 | +| Field or Attribute | Span Create A | Span Create B | Span Publish | Span Receive A | Span Receive B | |-|-|-|-|-|-| -| Span name | `"Q publish"` | `"Q publish"` | `"Q receive"` | `"Q receive"` | `"Q process"` | -| Parent | | | Span Prod1 | Span Prod2 | | -| Links | | | | | [Span Prod1, Span Prod2 ] | -| Link attributes | | | | | Span Prod1: `messaging.message.id`: `"a1"` | -| | | | | | Span Prod2: `messaging.message.id`: `"a2"` | -| SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` | `CONSUMER` | `CONSUMER` | -| Status | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` | +| Span name | `Q create` | `Q create` | `Q publish` | `Q receive` | `Q receive` | +| Parent | | | | | | +| Links | | | | Span Create A | Span Create B | +| SpanKind | `PRODUCER` | `PRODUCER` | `CLIENT` | `CONSUMER` | `CONSUMER` | | `server.address` | `"ms"` | `"ms"` | `"ms"` | `"ms"` | `"ms"` | | `server.port` | `1234` | `1234` | `1234` | `1234` | `1234` | -| `messaging.system` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` | +| `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | | `messaging.destination.name` | `"Q"` | `"Q"` | `"Q"` | `"Q"` | `"Q"` | -| `messaging.operation` | | | `"receive"` | `"receive"` | `"process"` | -| `messaging.message.id` | `"a1"` | `"a2"` | `"a1"` | `"a2"` | | -| `messaging.batch.message_count` | | | 1 | 1 | 2 | +| `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 @@ -423,4 +574,4 @@ More specific Semantic Conventions are defined for the following messaging techn * [RabbitMQ](rabbitmq.md): Semantic Conventions for *RabbitMQ*. * [RocketMQ](rocketmq.md): Semantic Conventions for *Apache RocketMQ*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md index 3c5bff049c..c489cb7ebb 100644 --- a/docs/messaging/rabbitmq.md +++ b/docs/messaging/rabbitmq.md @@ -6,7 +6,7 @@ linkTitle: RabbitMQ **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [RibbitMQ](https://www.rabbitmq.com/) extend and override the [Messaging Semantic Conventions](README.md) +The Semantic Conventions for [RabbitMQ](https://www.rabbitmq.com/) 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. @@ -17,10 +17,15 @@ described on this page. In RabbitMQ, the destination is defined by an *exchange* and a *routing key*. `messaging.destination.name` MUST be set to the name of the exchange. This will be an empty string if the default exchange is used. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `messaging.rabbitmq.destination.routing_key` | string | RabbitMQ message routing key. | `myKey` | Conditionally Required: If not empty. | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`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) | +| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the messaging intermediary node where the operation was performed. [1] | `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 of the messaging intermediary node where the operation was performed. | `65123` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** If an operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md index a0b88daa06..6d99d19fab 100644 --- a/docs/messaging/rocketmq.md +++ b/docs/messaging/rocketmq.md @@ -16,40 +16,40 @@ described on this page. Specific attributes for Apache RocketMQ are defined below. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `messaging.rocketmq.namespace` | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | Required | -| `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` | Required | -| `messaging.rocketmq.message.delivery_timestamp` | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | Conditionally Required: [1] | -| `messaging.rocketmq.message.delay_time_level` | int | The delay time level for delay message, which determines the message delay time. | `3` | Conditionally Required: [2] | -| `messaging.rocketmq.message.group` | 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. | -| `messaging.rocketmq.message.type` | string | Type of message. | `normal` | Recommended | -| `messaging.rocketmq.message.tag` | string | The secondary classifier of message besides topic. | `tagA` | Recommended | -| `messaging.rocketmq.message.keys` | string[] | Key(s) of message, another way to mark message besides message id. | `[keyA, keyB]` | Recommended | -| `messaging.rocketmq.consumption_model` | string | Model of message consumption. This only applies to consumer spans. | `clustering` | Recommended | - -**[1]:** If the message type is delay and delay time level is not specified. - -**[2]:** If the message type is delay and delivery timestamp is not specified. - -`messaging.rocketmq.message.type` MUST be one of the following: - -| Value | Description | -|---|---| -| `normal` | Normal message | -| `fifo` | FIFO message | -| `delay` | Delay message | -| `transaction` | Transaction message | - -`messaging.rocketmq.consumption_model` MUST be one of the following: - -| Value | Description | -|---|---| -| `clustering` | Clustering consumption model | -| `broadcasting` | Broadcasting consumption model | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`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.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) | +| [`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` [1] | ![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` [2] | ![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) | +| [`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) | + +**[1]:** If the message type is delay and delivery timestamp is not specified. + +**[2]:** If the message type is delay and delay time level is not specified. + +`messaging.rocketmq.consumption_model` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `clustering` | Clustering consumption model | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `broadcasting` | Broadcasting consumption model | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`messaging.rocketmq.message.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `normal` | Normal message | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `fifo` | FIFO message | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `delay` | Delay message | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `transaction` | Transaction message | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `messaging.client_id` SHOULD be set to the client ID that is automatically generated by the Apache RocketMQ SDK. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/mobile/README.md b/docs/mobile/README.md new file mode 100644 index 0000000000..cc6ffb6285 --- /dev/null +++ b/docs/mobile/README.md @@ -0,0 +1,18 @@ + + +# Semantic Convention for Mobile Platform + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions for mobile platform spans, metrics and logs. + +Semantic conventions for the mobile platform are defined for the following signals: + +* [Mobile Events](events.md) : Semantic Conventions for mobile events in *logs*. + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/mobile/events.md b/docs/mobile/events.md new file mode 100644 index 0000000000..dd363ee9bc --- /dev/null +++ b/docs/mobile/events.md @@ -0,0 +1,69 @@ +# Semantic Conventions for mobile events + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions for instrumentations that emit +events on mobile platforms. All mobile events MUST use a namespace of +`device` in the `event.name` property. + + + +- [Lifecycle instrumentation](#lifecycle-instrumentation) + - [Event details](#event-details) + + + +## Lifecycle instrumentation + +This section defines how to apply semantic conventions when instrumenting +application lifecycle. This event is meant to be used in conjunction with +`os.name` [resource semantic convention](/docs/resource/os.md) to identify the +mobile operating system (e.g. Android, iOS). + +The following table describes the payload fields that MUST +be used to describe the state of the application at the time of the event. + +The `android.state` and `ios.state` fields are mutually exclusive and MUST +NOT be used together, each field MUST be used with its corresponding +`os.name` [resource semantic convention](/docs/resource/os.md) value. + +### Event details + + + + + +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `android.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `created` | `Conditionally Required`: if and only if `os.name` is `android` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ios.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [2] | `active` | `Conditionally Required`: if and only if `os.name` is `ios` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived. + +**[2]:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived. + +**Additional attribute requirements:** At least one of the following sets of attributes is required: + +* `ios.state` +* `android.state` + +`android.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `created` | Any time before Activity.onResume() or, if the app has no Activity, Context.startService() has been called in the app for the first time. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `background` | Any time after Activity.onPause() or, if the app has no Activity, Context.stopService() has been called when the app was in the foreground state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `foreground` | Any time after Activity.onResume() or, if the app has no Activity, Context.startService() has been called when the app was in either the created or background states. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`ios.state` MUST be one of the following: + +| Value | Description | Stability | +|---|---|---| +| `active` | The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `inactive` | The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `background` | The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `foreground` | The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `terminate` | The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/object-stores/README.md b/docs/object-stores/README.md index 3dd2eb6715..21189287ba 100644 --- a/docs/object-stores/README.md +++ b/docs/object-stores/README.md @@ -1,7 +1,7 @@ @@ -15,4 +15,4 @@ The following technology specific semantic conventions are defined for object st * [AWS S3](s3.md): Semantic Conventions for *AWS S3*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/object-stores/s3.md b/docs/object-stores/s3.md index 71d6c56360..3ac6a0ab8f 100644 --- a/docs/object-stores/s3.md +++ b/docs/object-stores/s3.md @@ -12,19 +12,30 @@ that describe common AWS SDK attributes in addition to the Semantic Conventions described on this page. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.s3.bucket` | string | The S3 bucket name the request refers to. Corresponds to the `--bucket` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [1] | `some-bucket-name` | Recommended | -| `aws.s3.key` | string | The S3 object key the request refers to. Corresponds to the `--key` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [2] | `someFile.yml` | Recommended | -| `aws.s3.copy_source` | string | The source object (in the form `bucket`/`key`) for the copy operation. [3] | `someFile.yml` | Recommended | -| `aws.s3.upload_id` | string | Upload ID that identifies the multipart upload. [4] | `dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ` | Recommended | -| `aws.s3.delete` | string | The delete request container that specifies the objects to be deleted. [5] | `Objects=[{Key=string,VersionId=string},{Key=string,VersionId=string}],Quiet=boolean` | Recommended | -| `aws.s3.part_number` | int | The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000. [6] | `3456` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`aws.s3.bucket`](../attributes-registry/aws.md) | string | The S3 bucket name the request refers to. Corresponds to the `--bucket` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [1] | `some-bucket-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.s3.copy_source`](../attributes-registry/aws.md) | string | The source object (in the form `bucket`/`key`) for the copy operation. [2] | `someFile.yml` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.s3.delete`](../attributes-registry/aws.md) | string | The delete request container that specifies the objects to be deleted. [3] | `Objects=[{Key=string,VersionId=string},{Key=string,VersionId=string}],Quiet=boolean` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.s3.key`](../attributes-registry/aws.md) | string | The S3 object key the request refers to. Corresponds to the `--key` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [4] | `someFile.yml` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.s3.part_number`](../attributes-registry/aws.md) | int | The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000. [5] | `3456` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.s3.upload_id`](../attributes-registry/aws.md) | string | Upload ID that identifies the multipart upload. [6] | `dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter. This applies to almost all S3 operations except `list-buckets`. -**[2]:** The `key` attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter. +**[2]:** The `copy_source` attribute applies to S3 copy operations and corresponds to the `--copy-source` parameter +of the [copy-object operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html). +This applies in particular to the following operations: + +- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) +- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) + +**[3]:** The `delete` attribute is only applicable to the [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) operation. +The `delete` attribute corresponds to the `--delete` parameter of the +[delete-objects operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-objects.html). + +**[4]:** The `key` attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter. This applies in particular to the following operations: - [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) @@ -41,14 +52,12 @@ This applies in particular to the following operations: - [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) -**[3]:** The `copy_source` attribute applies to S3 copy operations and corresponds to the `--copy-source` parameter -of the [copy-object operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html). -This applies in particular to the following operations: - -- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) -- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) +**[5]:** The `part_number` attribute is only applicable to the [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) +and [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) operations. +The `part_number` attribute corresponds to the `--part-number` parameter of the +[upload-part operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html). -**[4]:** The `upload_id` attribute applies to S3 multipart-upload operations and corresponds to the `--upload-id` parameter +**[6]:** The `upload_id` attribute applies to S3 multipart-upload operations and corresponds to the `--upload-id` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) multipart operations. This applies in particular to the following operations: @@ -57,15 +66,6 @@ This applies in particular to the following operations: - [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html) - [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) - -**[5]:** The `delete` attribute is only applicable to the [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) operation. -The `delete` attribute corresponds to the `--delete` parameter of the -[delete-objects operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-objects.html). - -**[6]:** The `part_number` attribute is only applicable to the [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) -and [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) operations. -The `part_number` attribute corresponds to the `--part-number` parameter of the -[upload-part operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html). -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/README.md b/docs/resource/README.md index 0426bd6249..7128009d5f 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -1,7 +1,7 @@ @@ -9,7 +9,7 @@ path_base_for_github_subdir: **Status**: [Mixed][DocumentStatus] -This document defines standard attributes for resources. These attributes are typically used in the [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md) and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from +This document defines standard attributes for resources. These attributes are typically used in the [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/resource/sdk.md) and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from [OpenCensus Resource standard](https://github.com/census-instrumentation/opencensus-specs/blob/master/resource/StandardResources.md). @@ -19,12 +19,12 @@ This document defines standard attributes for resources. These attributes are ty - [TODOs](#todos) - [Document Conventions](#document-conventions) - [Attributes with Special Handling](#attributes-with-special-handling) - * [Semantic Attributes with Dedicated Environment Variable](#semantic-attributes-with-dedicated-environment-variable) -- [Semantic Attributes with SDK-provided Default Value](#semantic-attributes-with-sdk-provided-default-value) + - [Semantic Attributes with Dedicated Environment Variable](#semantic-attributes-with-dedicated-environment-variable) + - [Semantic Attributes with SDK-provided Default Value](#semantic-attributes-with-sdk-provided-default-value) - [Service](#service) - [Service (Experimental)](#service-experimental) - [Telemetry SDK](#telemetry-sdk) -- [Telemetry SDK (Experimental)](#telemetry-sdk-experimental) +- [Telemetry Distribution (Experimental)](#telemetry-distribution-experimental) - [Compute Unit](#compute-unit) - [Compute Instance](#compute-instance) - [Environment](#environment) @@ -47,7 +47,7 @@ This document defines standard attributes for resources. These attributes are ty Attributes are grouped logically by the type of the concept that they described. Attributes in the same group have a common prefix that ends with a dot. For example all attributes that describe Kubernetes properties start with "k8s." -See [Attribute Requirement Levels](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/common/attribute-requirement-level.md) for details on when attributes +See [Attribute Requirement Levels](../general/attribute-requirement-level.md) for details on when attributes should be included. ## Attributes with Special Handling @@ -59,15 +59,14 @@ Given their significance some resource attributes are treated specifically as de ### Semantic Attributes with Dedicated Environment Variable These are the attributes which MAY be configurable via a dedicated environment variable -as specified in [OpenTelemetry Environment Variable Specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/configuration/sdk-environment-variables.md): +as specified in [OpenTelemetry Environment Variable Specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/configuration/sdk-environment-variables.md): - [`service.name`](#service) -- [`service.version`](#service) -## Semantic Attributes with SDK-provided Default Value +### Semantic Attributes with SDK-provided Default Value These are the attributes which MUST be provided by the SDK -as specified in the [Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md#sdk-provided-resource-attributes): +as specified in the [Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/resource/sdk.md#sdk-provided-resource-attributes): - [`service.name`](#service) - [`telemetry.sdk` group](#telemetry-sdk) @@ -81,12 +80,12 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet **Description:** A service instance. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `service.name` | string | Logical name of the service. [1] | `shoppingcart` | Required | -| `service.version` | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`service.name`](/docs/attributes-registry/service.md) | string | Logical name of the service. [1] | `shoppingcart` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`service.version`](/docs/attributes-registry/service.md) | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md#process), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. +**[1]:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. ## Service (Experimental) @@ -98,14 +97,39 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet **Description:** Additions to service instance. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `service.namespace` | string | A namespace for `service.name`. [1] | `Shop` | Recommended | -| `service.instance.id` | string | The string ID of the service instance. [2] | `my-k8s-pod-deployment-1`; `627cc493-f310-47de-96bd-71410b7dec09` | Recommended | - -**[1]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. - -**[2]:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words `service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled service). It is preferable for the ID to be persistent and stay the same for the lifetime of the service instance, however it is acceptable that the ID is ephemeral and changes during important lifetime events for the service (e.g. service restarts). If the service has no inherent unique ID that can be used as the value of this attribute it is recommended to generate a random Version 1 or Version 4 RFC 4122 UUID (services aiming for reproducible UUIDs may also use Version 5, see RFC 4122 for more recommendations). +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`service.instance.id`](/docs/attributes-registry/service.md) | string | The string ID of the service instance. [1] | `627cc493-f310-47de-96bd-71410b7dec09` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`service.namespace`](/docs/attributes-registry/service.md) | string | A namespace for `service.name`. [2] | `Shop` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words +`service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to +distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled +service). + +Implementations, such as SDKs, are recommended to generate a random Version 1 or Version 4 [RFC +4122](https://www.ietf.org/rfc/rfc4122.txt) UUID, but are free to use an inherent unique ID as the source of +this value if stability is desirable. In that case, the ID SHOULD be used as source of a UUID Version 5 and +SHOULD use the following UUID as the namespace: `4d63009a-8d0f-11ee-aad7-4c796ed8e320`. + +UUIDs are typically recommended, as only an opaque value for the purposes of identifying a service instance is +needed. Similar to what can be seen in the man page for the +[`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/machine-id.html) file, the underlying +data, such as pod name and namespace should be treated as confidential, being the user's choice to expose it +or not via another resource attribute. + +For applications running behind an application server (like unicorn), we do not recommend using one identifier +for all processes participating in the application. Instead, it's recommended each division (e.g. a worker +thread in unicorn) to have its own instance.id. + +It's not recommended for a Collector to set `service.instance.id` if it can't unambiguously determine the +service instance that is generating that telemetry. For instance, creating an UUID based on `pod.name` will +likely be wrong, as the Collector might not know from which container within that pod the telemetry originated. +However, Collectors can set the `service.instance.id` if they can unambiguously determine the service instance +for that telemetry. This is typically the case for scraping receivers, as they know the target address and +port. + +**[2]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. Note: `service.namespace` and `service.name` are not intended to be concatenated for the purpose of forming a single globally unique name for the service. For example the following 2 sets of attributes actually describe 2 different services (despite the fact that the concatenation would result in the same string): @@ -130,12 +154,12 @@ service.name = Shop.shoppingcart **Description:** The telemetry SDK used to capture data recorded by the instrumentation libraries. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [1] | `opentelemetry` | Required | -| `telemetry.sdk.language` | string | The language of the telemetry SDK. | `cpp` | Required | -| `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` | Required | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`telemetry.sdk.language`](/docs/attributes-registry/telemetry.md) | string | The language of the telemetry SDK. | `cpp`; `dotnet`; `erlang` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`telemetry.sdk.name`](/docs/attributes-registry/telemetry.md) | string | The name of the telemetry SDK as defined above. [1] | `opentelemetry` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`telemetry.sdk.version`](/docs/attributes-registry/telemetry.md) | string | The version string of the telemetry SDK. | `1.2.3` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the @@ -144,36 +168,40 @@ or another suitable identifier depending on the language. The identifier `opentelemetry` is reserved and MUST NOT be used in this case. All custom identifiers SHOULD be stable across different versions of an implementation. -`telemetry.sdk.language` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. - -| Value | Description | -|---|---| -| `cpp` | cpp | -| `dotnet` | dotnet | -| `erlang` | erlang | -| `go` | go | -| `java` | java | -| `nodejs` | nodejs | -| `php` | php | -| `python` | python | -| `ruby` | ruby | -| `rust` | rust | -| `swift` | swift | -| `webjs` | webjs | +`telemetry.sdk.language` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `cpp` | cpp | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `dotnet` | dotnet | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `erlang` | erlang | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `go` | go | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `java` | java | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `nodejs` | nodejs | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `php` | php | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `python` | python | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ruby` | ruby | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `rust` | rust | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `swift` | swift | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `webjs` | webjs | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -## Telemetry SDK (Experimental) +## Telemetry Distribution (Experimental) **Status**: [Experimental][DocumentStatus] -**type:** `telemetry.sdk` +**type:** `telemetry.distro` -**Description:** Additions to the telemetry SDK. +**Description:** The telemetry distribution (distro) used to capture data recorded by the instrumentation libraries. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `telemetry.auto.version` | string | The version string of the auto instrumentation agent, if used. | `1.2.3` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`telemetry.distro.name`](/docs/attributes-registry/telemetry.md) | string | The name of the auto instrumentation agent or distribution, if used. [1] | `parts-unlimited-java` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`telemetry.distro.version`](/docs/attributes-registry/telemetry.md) | string | The version string of the auto instrumentation agent or distribution, if used. | `1.2.3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Official auto instrumentation agents and distributions SHOULD set the `telemetry.distro.name` attribute to +a string starting with `opentelemetry-`, e.g. `opentelemetry-java-instrumentation`. ## Compute Unit @@ -233,4 +261,4 @@ Valid cloud providers are: - [Tencent Cloud](https://www.tencentcloud.com/) (`tencent_cloud`) - [Heroku dyno](./cloud-provider/heroku.md) -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/android.md b/docs/resource/android.md new file mode 100644 index 0000000000..23c7edb1c3 --- /dev/null +++ b/docs/resource/android.md @@ -0,0 +1,15 @@ +# Android + +**Status**: [Experimental][DocumentStatus] + +**type:** `android` + +**Description**: The Android platform on which the Android application is running. + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`android.os.api_level`](/docs/attributes-registry/android.md) | string | Uniquely identifies the framework API revision offered by a version (`os.version`) of the android operating system. More information can be found [here](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels). | `33`; `32` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/browser.md b/docs/resource/browser.md index a914a1f24e..767bfbc359 100644 --- a/docs/resource/browser.md +++ b/docs/resource/browser.md @@ -9,24 +9,24 @@ All of these attributes can be provided by the user agent itself in the form of an HTTP header (e.g. Sec-CH-UA, Sec-CH-Platform, User-Agent). However, the headers could be removed by proxy servers, and are tied to calls from individual clients. In order to support batching through services like the Collector and to prevent loss of data (e.g. due to proxy servers removing headers), these attributes should be used when possible. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `browser.brands` | string[] | Array of brand name and version separated by a space [1] | `[ Not A;Brand 99, Chromium 99, Chrome 99]` | Recommended | -| `browser.platform` | string | The platform on which the browser is running [2] | `Windows`; `macOS`; `Android` | Recommended | -| `browser.mobile` | boolean | A boolean that is true if the browser is running on a mobile device [3] | | Recommended | -| `browser.language` | string | Preferred language of the user using the browser [4] | `en`; `en-US`; `fr`; `fr-FR` | Recommended | -| `user_agent.original` | string | Full user-agent string provided by the browser [5] | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`browser.brands`](/docs/attributes-registry/browser.md) | string[] | Array of brand name and version separated by a space [1] | ` Not A;Brand 99`; `Chromium 99`; `Chrome 99` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`browser.language`](/docs/attributes-registry/browser.md) | string | Preferred language of the user using the browser [2] | `en`; `en-US`; `fr`; `fr-FR` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`browser.mobile`](/docs/attributes-registry/browser.md) | boolean | A boolean that is true if the browser is running on a mobile device [3] | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`browser.platform`](/docs/attributes-registry/browser.md) | string | The platform on which the browser is running [4] | `Windows`; `macOS`; `Android` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string provided by the browser [5] | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`). -**[2]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent. -The list of possible values is defined in the [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). Note that some (but not all) of these values can overlap with values in the [`os.type` and `os.name` attributes](./os.md). However, for consistency, the values in the `browser.platform` attribute should capture the exact value that the user agent provides. +**[2]:** This value is intended to be taken from the Navigator API `navigator.language`. **[3]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.mobile`). If unavailable, this attribute SHOULD be left unset. -**[4]:** This value is intended to be taken from the Navigator API `navigator.language`. +**[4]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent. +The list of possible values is defined in the [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). Note that some (but not all) of these values can overlap with values in the [`os.type` and `os.name` attributes](./os.md). However, for consistency, the values in the `browser.platform` attribute should capture the exact value that the user agent provides. **[5]:** The user-agent value SHOULD be provided only from browsers that do not have a mechanism to retrieve brands and platform individually from the User-Agent Client Hints API. To retrieve the value, the legacy `navigator.userAgent` API can be used. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/cloud-provider/README.md b/docs/resource/cloud-provider/README.md index 40e4d4822a..074f5d473f 100644 --- a/docs/resource/cloud-provider/README.md +++ b/docs/resource/cloud-provider/README.md @@ -1,7 +1,7 @@ @@ -15,4 +15,4 @@ This document defines semantic conventions for resource cloud providers. * [GCP](gcp/README.md): Semantic Conventions for Google Cloud Platform. * [Heroku](heroku.md): Semantic Conventions for Heroku. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/cloud-provider/aws/README.md b/docs/resource/cloud-provider/aws/README.md index 3e20b6848e..1cf7113b3d 100644 --- a/docs/resource/cloud-provider/aws/README.md +++ b/docs/resource/cloud-provider/aws/README.md @@ -1,7 +1,7 @@ @@ -28,4 +28,4 @@ Attributes that relate to an individual AWS service: - [Elastic Container Service (ECS)](./ecs.md) - [Elastic Kubernetes Service (EKS)](./eks.md) -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/cloud-provider/aws/ecs.md b/docs/resource/cloud-provider/aws/ecs.md index ba3ae6183b..6a6da8e2eb 100644 --- a/docs/resource/cloud-provider/aws/ecs.md +++ b/docs/resource/cloud-provider/aws/ecs.md @@ -6,22 +6,23 @@ **Description:** Resources used by AWS Elastic Container Service (ECS). - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.ecs.container.arn` | string | The Amazon Resource Name (ARN) of an [ECS container instance](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html). | `arn:aws:ecs:us-west-1:123456789123:container/32624152-9086-4f0e-acae-1a75b14fe4d9` | Recommended | -| `aws.ecs.cluster.arn` | string | The ARN of an [ECS cluster](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/clusters.html). | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | Recommended | -| `aws.ecs.launchtype` | string | The [launch type](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_types.html) for an ECS task. | `ec2` | Recommended | -| `aws.ecs.task.arn` | string | The ARN of an [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html). | `arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b` | Recommended | -| `aws.ecs.task.family` | string | The task definition family this task definition is a member of. | `opentelemetry-family` | Recommended | -| `aws.ecs.task.revision` | string | The revision for this task definition. | `8`; `26` | Recommended | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`aws.ecs.task.id`](/docs/attributes-registry/aws.md) | string | The ID of a running ECS task. The ID MUST be extracted from `task.arn`. | `10838bed-421f-43ef-870a-f43feacbbb5b`; `23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd` | `Conditionally Required` If and only if `task.arn` is populated. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.ecs.cluster.arn`](/docs/attributes-registry/aws.md) | string | The ARN of an [ECS cluster](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/clusters.html). | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.ecs.container.arn`](/docs/attributes-registry/aws.md) | string | The Amazon Resource Name (ARN) of an [ECS container instance](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html). | `arn:aws:ecs:us-west-1:123456789123:container/32624152-9086-4f0e-acae-1a75b14fe4d9` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.ecs.launchtype`](/docs/attributes-registry/aws.md) | string | The [launch type](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_types.html) for an ECS task. | `ec2`; `fargate` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.ecs.task.arn`](/docs/attributes-registry/aws.md) | string | The ARN of a running [ECS task](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-account-settings.html#ecs-resource-ids). | `arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b`; `arn:aws:ecs:us-west-1:123456789123:task/my-cluster/task-id/23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.ecs.task.family`](/docs/attributes-registry/aws.md) | string | The family name of the [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) used to create the ECS task. | `opentelemetry-family` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.ecs.task.revision`](/docs/attributes-registry/aws.md) | string | The revision for the task definition used to create the ECS task. | `8`; `26` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`aws.ecs.launchtype` MUST be one of the following: +`aws.ecs.launchtype` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Value | Description | -|---|---| -| `ec2` | ec2 | -| `fargate` | fargate | +| Value | Description | Stability | +|---|---|---| +| `ec2` | ec2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `fargate` | fargate | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/cloud-provider/aws/eks.md b/docs/resource/cloud-provider/aws/eks.md index 765108afce..8133eafec7 100644 --- a/docs/resource/cloud-provider/aws/eks.md +++ b/docs/resource/cloud-provider/aws/eks.md @@ -7,9 +7,9 @@ **Description:** Resources used by AWS Elastic Kubernetes Service (EKS). -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.eks.cluster.arn` | string | The ARN of an EKS cluster. | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`aws.eks.cluster.arn`](/docs/attributes-registry/aws.md) | string | The ARN of an EKS cluster. | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/cloud-provider/aws/logs.md b/docs/resource/cloud-provider/aws/logs.md index d2238e68d6..4a6d764719 100644 --- a/docs/resource/cloud-provider/aws/logs.md +++ b/docs/resource/cloud-provider/aws/logs.md @@ -7,18 +7,18 @@ **Description:** Log attributes for Amazon Web Services. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.log.group.names` | string[] | The name(s) of the AWS log group(s) an application is writing to. [1] | `[/aws/lambda/my-function, opentelemetry-service]` | Recommended | -| `aws.log.group.arns` | string[] | The Amazon Resource Name(s) (ARN) of the AWS log group(s). [2] | `[arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:*]` | Recommended | -| `aws.log.stream.names` | string[] | The name(s) of the AWS log stream(s) an application is writing to. | `[logs/main/10838bed-421f-43ef-870a-f43feacbbb5b]` | Recommended | -| `aws.log.stream.arns` | string[] | The ARN(s) of the AWS log stream(s). [3] | `[arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:log-stream:logs/main/10838bed-421f-43ef-870a-f43feacbbb5b]` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`aws.log.group.arns`](/docs/attributes-registry/aws.md) | string[] | The Amazon Resource Name(s) (ARN) of the AWS log group(s). [1] | `arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:*` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.log.group.names`](/docs/attributes-registry/aws.md) | string[] | The name(s) of the AWS log group(s) an application is writing to. [2] | `/aws/lambda/my-function`; `opentelemetry-service` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.log.stream.arns`](/docs/attributes-registry/aws.md) | string[] | The ARN(s) of the AWS log stream(s). [3] | `arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:log-stream:logs/main/10838bed-421f-43ef-870a-f43feacbbb5b` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.log.stream.names`](/docs/attributes-registry/aws.md) | string[] | The name(s) of the AWS log stream(s) an application is writing to. | `logs/main/10838bed-421f-43ef-870a-f43feacbbb5b` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** Multiple log groups must be supported for cases like multi-container applications, where a single application has sidecar containers, and each write to their own log group. +**[1]:** See the [log group ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). -**[2]:** See the [log group ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). +**[2]:** Multiple log groups must be supported for cases like multi-container applications, where a single application has sidecar containers, and each write to their own log group. **[3]:** See the [log stream ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). One log group can contain several log streams, so these ARNs necessarily identify both a log group and a log stream. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/cloud-provider/gcp/README.md b/docs/resource/cloud-provider/gcp/README.md index 6888ead5a1..18e17e81f9 100644 --- a/docs/resource/cloud-provider/gcp/README.md +++ b/docs/resource/cloud-provider/gcp/README.md @@ -1,7 +1,7 @@ @@ -19,4 +19,4 @@ provider (like account ID, operating system, etc), it belongs in the parent - [Cloud Run](./cloud-run.md) - [Compute Engine](./gce.md) -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/cloud-provider/gcp/cloud-run.md b/docs/resource/cloud-provider/gcp/cloud-run.md index ce884d3e1e..572a0e0a7c 100644 --- a/docs/resource/cloud-provider/gcp/cloud-run.md +++ b/docs/resource/cloud-provider/gcp/cloud-run.md @@ -9,10 +9,10 @@ These conventions are recommended for resources running on Cloud Run. **Description:** Resource attributes for Cloud Run. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `gcp.cloud_run.job.execution` | string | The name of the Cloud Run [execution](https://cloud.google.com/run/docs/managing/job-executions) being run for the Job, as set by the [`CLOUD_RUN_EXECUTION`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `job-name-xxxx`; `sample-job-mdw84` | Recommended | -| `gcp.cloud_run.job.task_index` | int | The index for a task within an execution as provided by the [`CLOUD_RUN_TASK_INDEX`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `0`; `1` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gcp.cloud_run.job.execution`](/docs/attributes-registry/gcp.md) | string | The name of the Cloud Run [execution](https://cloud.google.com/run/docs/managing/job-executions) being run for the Job, as set by the [`CLOUD_RUN_EXECUTION`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `job-name-xxxx`; `sample-job-mdw84` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gcp.cloud_run.job.task_index`](/docs/attributes-registry/gcp.md) | int | The index for a task within an execution as provided by the [`CLOUD_RUN_TASK_INDEX`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `0`; `1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/cloud-provider/gcp/gce.md b/docs/resource/cloud-provider/gcp/gce.md index 49d9954643..0798bc042e 100644 --- a/docs/resource/cloud-provider/gcp/gce.md +++ b/docs/resource/cloud-provider/gcp/gce.md @@ -5,8 +5,8 @@ **Description:** Resource attributes for GCE instances. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `gcp.gce.instance.name` | string | The instance name of a GCE instance. This is the value provided by `host.name`, the visible name of the instance in the Cloud Console UI, and the prefix for the default hostname of the instance as defined by the [default internal DNS name](https://cloud.google.com/compute/docs/internal-dns#instance-fully-qualified-domain-names). | `instance-1`; `my-vm-name` | Recommended | -| `gcp.gce.instance.hostname` | string | The hostname of a GCE instance. This is the full value of the default or [custom hostname](https://cloud.google.com/compute/docs/instances/custom-hostname-vm). | `my-host1234.example.com`; `sample-vm.us-west1-b.c.my-project.internal` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gcp.gce.instance.hostname`](/docs/attributes-registry/gcp.md) | string | The hostname of a GCE instance. This is the full value of the default or [custom hostname](https://cloud.google.com/compute/docs/instances/custom-hostname-vm). | `my-host1234.example.com`; `sample-vm.us-west1-b.c.my-project.internal` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gcp.gce.instance.name`](/docs/attributes-registry/gcp.md) | string | The instance name of a GCE instance. This is the value provided by `host.name`, the visible name of the instance in the Cloud Console UI, and the prefix for the default hostname of the instance as defined by the [default internal DNS name](https://cloud.google.com/compute/docs/internal-dns#instance-fully-qualified-domain-names). | `instance-1`; `my-vm-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/resource/cloud-provider/heroku.md b/docs/resource/cloud-provider/heroku.md index fb0171cd75..c7b30e8e77 100644 --- a/docs/resource/cloud-provider/heroku.md +++ b/docs/resource/cloud-provider/heroku.md @@ -7,11 +7,11 @@ **Description:** [Heroku dyno metadata] -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `heroku.release.creation_timestamp` | string | Time and date the release was created | `2022-10-23T18:00:42Z` | Opt-In | -| `heroku.release.commit` | string | Commit hash for the current release | `e6134959463efd8966b20e75b913cafe3f5ec` | Opt-In | -| `heroku.app.id` | string | Unique identifier for the application | `2daa2797-e42b-4624-9322-ec3f968df4da` | Opt-In | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`heroku.app.id`](/docs/attributes-registry/heroku.md) | string | Unique identifier for the application | `2daa2797-e42b-4624-9322-ec3f968df4da` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`heroku.release.commit`](/docs/attributes-registry/heroku.md) | string | Commit hash for the current release | `e6134959463efd8966b20e75b913cafe3f5ec` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`heroku.release.creation_timestamp`](/docs/attributes-registry/heroku.md) | string | Time and date the release was created | `2022-10-23T18:00:42Z` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **Mapping:** @@ -29,4 +29,4 @@ Additionally, [the `cloud.provider` resource attribute MUST be set to `heroku`]( [Heroku dyno metadata]: https://devcenter.heroku.com/articles/dyno-metadata -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/cloud.md b/docs/resource/cloud.md index 7967c30976..797e219b3e 100644 --- a/docs/resource/cloud.md +++ b/docs/resource/cloud.md @@ -6,19 +6,23 @@ **Description:** A cloud infrastructure (e.g. GCP, Azure, AWS). - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `cloud.provider` | string | Name of the cloud provider. | `alibaba_cloud` | Recommended | -| `cloud.account.id` | string | The cloud account ID the resource is assigned to. | `111111111111`; `opentelemetry` | Recommended | -| `cloud.region` | string | The geographical region the resource is running. [1] | `us-central1`; `us-east-1` | Recommended | -| `cloud.resource_id` | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [2] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | -| `cloud.availability_zone` | string | Cloud regions often have multiple, isolated locations known as zones to increase availability. Availability zone represents the zone where the resource is running. [3] | `us-east-1c` | Recommended | -| `cloud.platform` | string | The cloud platform in use. [4] | `alibaba_cloud_ecs` | Recommended | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`cloud.account.id`](/docs/attributes-registry/cloud.md) | string | The cloud account ID the resource is assigned to. | `111111111111`; `opentelemetry` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`cloud.availability_zone`](/docs/attributes-registry/cloud.md) | string | Cloud regions often have multiple, isolated locations known as zones to increase availability. Availability zone represents the zone where the resource is running. [1] | `us-east-1c` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`cloud.platform`](/docs/attributes-registry/cloud.md) | string | The cloud platform in use. [2] | `alibaba_cloud_ecs`; `alibaba_cloud_fc`; `alibaba_cloud_openshift` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`cloud.provider`](/docs/attributes-registry/cloud.md) | string | Name of the cloud provider. | `alibaba_cloud`; `aws`; `azure` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`cloud.region`](/docs/attributes-registry/cloud.md) | string | The geographical region the resource is running. [3] | `us-central1`; `us-east-1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`cloud.resource_id`](/docs/attributes-registry/cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [4] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** Refer to your provider's docs to see the available regions, for example [Alibaba Cloud regions](https://www.alibabacloud.com/help/doc-detail/40654.htm), [AWS regions](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/), [Azure regions](https://azure.microsoft.com/en-us/global-infrastructure/geographies/), [Google Cloud regions](https://cloud.google.com/about/locations), or [Tencent Cloud regions](https://www.tencentcloud.com/document/product/213/6091). +**[1]:** Availability zones are called "zones" on Alibaba Cloud and Google Cloud. -**[2]:** On some cloud providers, it may not be possible to determine the full ID at startup, +**[2]:** The prefix of the service SHOULD match the one specified in `cloud.provider`. + +**[3]:** Refer to your provider's docs to see the available regions, for example [Alibaba Cloud regions](https://www.alibabacloud.com/help/doc-detail/40654.htm), [AWS regions](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/), [Azure regions](https://azure.microsoft.com/global-infrastructure/geographies/), [Google Cloud regions](https://cloud.google.com/about/locations), or [Tencent Cloud regions](https://www.tencentcloud.com/document/product/213/6091). + +**[4]:** On some cloud providers, it may not be possible to determine the full ID at startup, so it may be necessary to set `cloud.resource_id` as a span attribute instead. The exact value to use for `cloud.resource_id` depends on the cloud provider. @@ -30,59 +34,56 @@ The following well-known definitions MUST be used if you set this attribute and with the resolved function version, as the same runtime instance may be invokable with multiple different aliases. * **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) -* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id) of the invoked function, +* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/rest/api/resources/resources/get-by-id) of the invoked function, *not* the function app, having the form `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/`. This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share a TracerProvider. -**[3]:** Availability zones are called "zones" on Alibaba Cloud and Google Cloud. - -**[4]:** The prefix of the service SHOULD match the one specified in `cloud.provider`. - -`cloud.provider` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +`cloud.platform` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Value | Description | -|---|---| -| `alibaba_cloud` | Alibaba Cloud | -| `aws` | Amazon Web Services | -| `azure` | Microsoft Azure | -| `gcp` | Google Cloud Platform | -| `heroku` | Heroku Platform as a Service | -| `ibm_cloud` | IBM Cloud | -| `tencent_cloud` | Tencent Cloud | +| Value | Description | Stability | +|---|---|---| +| `alibaba_cloud_ecs` | Alibaba Cloud Elastic Compute Service | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `alibaba_cloud_fc` | Alibaba Cloud Function Compute | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `alibaba_cloud_openshift` | Red Hat OpenShift on Alibaba Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws_ec2` | AWS Elastic Compute Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws_ecs` | AWS Elastic Container Service | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws_eks` | AWS Elastic Kubernetes Service | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws_lambda` | AWS Lambda | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws_elastic_beanstalk` | AWS Elastic Beanstalk | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws_app_runner` | AWS App Runner | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws_openshift` | Red Hat OpenShift on AWS (ROSA) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure_vm` | Azure Virtual Machines | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure_container_apps` | Azure Container Apps | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure_container_instances` | Azure Container Instances | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure_aks` | Azure Kubernetes Service | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure_functions` | Azure Functions | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure_app_service` | Azure App Service | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure_openshift` | Azure Red Hat OpenShift | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp_bare_metal_solution` | Google Bare Metal Solution (BMS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp_compute_engine` | Google Cloud Compute Engine (GCE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp_cloud_run` | Google Cloud Run | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp_kubernetes_engine` | Google Cloud Kubernetes Engine (GKE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp_cloud_functions` | Google Cloud Functions (GCF) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp_app_engine` | Google Cloud App Engine (GAE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp_openshift` | Red Hat OpenShift on Google Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ibm_cloud_openshift` | Red Hat OpenShift on IBM Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tencent_cloud_cvm` | Tencent Cloud Cloud Virtual Machine (CVM) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tencent_cloud_eks` | Tencent Cloud Elastic Kubernetes Service (EKS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tencent_cloud_scf` | Tencent Cloud Serverless Cloud Function (SCF) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`cloud.platform` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +`cloud.provider` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Value | Description | -|---|---| -| `alibaba_cloud_ecs` | Alibaba Cloud Elastic Compute Service | -| `alibaba_cloud_fc` | Alibaba Cloud Function Compute | -| `alibaba_cloud_openshift` | Red Hat OpenShift on Alibaba Cloud | -| `aws_ec2` | AWS Elastic Compute Cloud | -| `aws_ecs` | AWS Elastic Container Service | -| `aws_eks` | AWS Elastic Kubernetes Service | -| `aws_lambda` | AWS Lambda | -| `aws_elastic_beanstalk` | AWS Elastic Beanstalk | -| `aws_app_runner` | AWS App Runner | -| `aws_openshift` | Red Hat OpenShift on AWS (ROSA) | -| `azure_vm` | Azure Virtual Machines | -| `azure_container_instances` | Azure Container Instances | -| `azure_aks` | Azure Kubernetes Service | -| `azure_functions` | Azure Functions | -| `azure_app_service` | Azure App Service | -| `azure_openshift` | Azure Red Hat OpenShift | -| `gcp_bare_metal_solution` | Google Bare Metal Solution (BMS) | -| `gcp_compute_engine` | Google Cloud Compute Engine (GCE) | -| `gcp_cloud_run` | Google Cloud Run | -| `gcp_kubernetes_engine` | Google Cloud Kubernetes Engine (GKE) | -| `gcp_cloud_functions` | Google Cloud Functions (GCF) | -| `gcp_app_engine` | Google Cloud App Engine (GAE) | -| `gcp_openshift` | Red Hat OpenShift on Google Cloud | -| `ibm_cloud_openshift` | Red Hat OpenShift on IBM Cloud | -| `tencent_cloud_cvm` | Tencent Cloud Cloud Virtual Machine (CVM) | -| `tencent_cloud_eks` | Tencent Cloud Elastic Kubernetes Service (EKS) | -| `tencent_cloud_scf` | Tencent Cloud Serverless Cloud Function (SCF) | +| Value | Description | Stability | +|---|---|---| +| `alibaba_cloud` | Alibaba Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws` | Amazon Web Services | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `azure` | Microsoft Azure | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gcp` | Google Cloud Platform | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `heroku` | Heroku Platform as a Service | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ibm_cloud` | IBM Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tencent_cloud` | Tencent Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/container.md b/docs/resource/container.md index 264a7d53bc..ce97e71bfc 100644 --- a/docs/resource/container.md +++ b/docs/resource/container.md @@ -7,23 +7,31 @@ **Description:** A container instance. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `container.name` | string | Container name used by container runtime. | `opentelemetry-autoconf` | Recommended | -| `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` | Recommended | -| `container.runtime` | string | The container runtime managing this container. | `docker`; `containerd`; `rkt` | Recommended | -| `container.image.name` | string | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` | Recommended | -| `container.image.tag` | string | Container image tag. | `0.1` | Recommended | -| `container.image.id` | string | Runtime specific image identifier. Usually a hash algorithm followed by a UUID. [1] | `sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f` | Recommended | -| `container.command` | string | The command used to run the container (i.e. the command name). [2] | `otelcontribcol` | Opt-In | -| `container.command_line` | string | The full command run by the container as a single string representing the full command. [2] | `otelcontribcol --config config.yaml` | Opt-In | -| `container.command_args` | string[] | All the command arguments (including the command/executable itself) run by the container. [2] | `[otelcontribcol, --config, config.yaml]` | Opt-In | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`container.id`](/docs/attributes-registry/container.md) | 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` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`container.image.id`](/docs/attributes-registry/container.md) | string | Runtime specific image identifier. Usually a hash algorithm followed by a UUID. [1] | `sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`container.image.name`](/docs/attributes-registry/container.md) | string | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`container.image.repo_digests`](/docs/attributes-registry/container.md) | string[] | Repo digests of the container image as provided by the container runtime. [2] | `example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb`; `internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`container.image.tags`](/docs/attributes-registry/container.md) | string[] | Container image tags. An example can be found in [Docker Image Inspect](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect). Should be only the `` section of the full name for example from `registry.example.com/my-org/my-image:`. | `v1.27.1`; `3.5.7-0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`container.label.`](/docs/attributes-registry/container.md) | string | Container labels, `` being the label name, the value being the label value. | `container.label.app=nginx` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`container.name`](/docs/attributes-registry/container.md) | string | Container name used by container runtime. | `opentelemetry-autoconf` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`container.runtime`](/docs/attributes-registry/container.md) | string | The container runtime managing this container. | `docker`; `containerd`; `rkt` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`oci.manifest.digest`](/docs/attributes-registry/oci.md) | string | The digest of the OCI image manifest. For container images specifically is the digest by which the container image is known. [3] | `sha256:e4ca62c0d62f3e886e684806dfe9d4e0cda60d54986898173c1083856cfda0f4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`container.command`](/docs/attributes-registry/container.md) | string | The command used to run the container (i.e. the command name). [4] | `otelcontribcol` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`container.command_args`](/docs/attributes-registry/container.md) | string[] | All the command arguments (including the command/executable itself) run by the container. [2] | `otelcontribcol, --config, config.yaml` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`container.command_line`](/docs/attributes-registry/container.md) | string | The full command run by the container as a single string representing the full command. [2] | `otelcontribcol --config config.yaml` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) endpoint. K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`. -OCI defines a digest of manifest. +The ID is assigned by the container runtime and can vary in different environments. Consider using `oci.manifest.digest` if it is important to identify the same image in different environments/runtimes. -**[2]:** If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. +**[2]:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field. + +**[3]:** Follows [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md), and specifically the [Digest property](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests). +An example can be found in [Example Image Manifest](https://docs.docker.com/registry/spec/manifest-v2-2/#example-image-manifest). + +**[4]:** If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/deployment-environment.md b/docs/resource/deployment-environment.md index 847283447d..dae823a128 100644 --- a/docs/resource/deployment-environment.md +++ b/docs/resource/deployment-environment.md @@ -7,9 +7,17 @@ **Description:** The software deployment. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `deployment.environment` | string | Name of the [deployment environment](https://en.wikipedia.org/wiki/Deployment_environment) (aka deployment tier). | `staging`; `production` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`deployment.environment`](/docs/attributes-registry/deployment.md) | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** `deployment.environment` does not affect the uniqueness constraints defined through +the `service.namespace`, `service.name` and `service.instance.id` resource attributes. +This implies that resources carrying the following attribute combinations MUST be +considered to be identifying the same service: + +* `service.name=frontend`, `deployment.environment=production` +* `service.name=frontend`, `deployment.environment=staging`. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/device.md b/docs/resource/device.md index 174057e861..bf927de0e8 100644 --- a/docs/resource/device.md +++ b/docs/resource/device.md @@ -7,20 +7,20 @@ **Description**: The device on which the process represented by this resource is running. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `device.id` | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | Recommended | -| `device.model.identifier` | string | The model identifier for the device [2] | `iPhone3,4`; `SM-G920F` | Recommended | -| `device.model.name` | string | The marketing name for the device model [3] | `iPhone 6s Plus`; `Samsung Galaxy S6` | Recommended | -| `device.manufacturer` | string | The name of the device manufacturer [4] | `Apple`; `Samsung` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`device.id`](/docs/attributes-registry/device.md) | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`device.manufacturer`](/docs/attributes-registry/device.md) | string | The name of the device manufacturer [2] | `Apple`; `Samsung` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`device.model.identifier`](/docs/attributes-registry/device.md) | string | The model identifier for the device [3] | `iPhone3,4`; `SM-G920F` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`device.model.name`](/docs/attributes-registry/device.md) | string | The marketing name for the device model [4] | `iPhone 6s Plus`; `Samsung Galaxy S6` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** The device identifier MUST only be defined using the values outlined below. This value is not an advertising identifier and MUST NOT be used as such. On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) on best practices and exact implementation details. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence. -**[2]:** It's recommended this value represents a machine readable version of the model identifier rather than the market or consumer-friendly name of the device. +**[2]:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`. -**[3]:** It's recommended this value represents a human readable version of the device model rather than a machine readable alternative. +**[3]:** It's recommended this value represents a machine-readable version of the model identifier rather than the market or consumer-friendly name of the device. -**[4]:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`. +**[4]:** It's recommended this value represents a human-readable version of the device model rather than a machine-readable alternative. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/faas.md b/docs/resource/faas.md index 4de83ef8d7..6e949d2abd 100644 --- a/docs/resource/faas.md +++ b/docs/resource/faas.md @@ -14,13 +14,13 @@ See also: ## FaaS resource attributes -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `faas.name` | string | The name of the single function that this runtime instance executes. [1] | `my-function`; `myazurefunctionapp/some-function-name` | Required | -| `faas.version` | string | The immutable version of the function being executed. [2] | `26`; `pinkfroid-00002` | Recommended | -| `faas.instance` | string | The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version. [3] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | Recommended | -| `faas.max_memory` | int | The amount of memory available to the serverless function converted to Bytes. [4] | `134217728` | Recommended | -| [`cloud.resource_id`](cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [5] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`faas.name`](/docs/attributes-registry/faas.md) | string | The name of the single function that this runtime instance executes. [1] | `my-function`; `myazurefunctionapp/some-function-name` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`cloud.resource_id`](/docs/attributes-registry/cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [2] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`faas.instance`](/docs/attributes-registry/faas.md) | string | The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version. [3] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`faas.max_memory`](/docs/attributes-registry/faas.md) | int | The amount of memory available to the serverless function converted to Bytes. [4] | `134217728` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`faas.version`](/docs/attributes-registry/faas.md) | string | The immutable version of the function being executed. [5] | `26`; `pinkfroid-00002` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** This is the name of the function as configured/deployed on the FaaS platform and is usually different from the name of the callback @@ -39,21 +39,7 @@ definition of function name MUST be used for this attribute app can host multiple functions that would usually share a TracerProvider (see also the `cloud.resource_id` attribute). -**[2]:** Depending on the cloud provider and platform, use: - -* **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) - (an integer represented as a decimal string). -* **Google Cloud Run (Services):** The [revision](https://cloud.google.com/run/docs/managing/revisions) - (i.e., the function name plus the revision suffix). -* **Google Cloud Functions:** The value of the - [`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically). -* **Azure Functions:** Not applicable. Do not set this attribute. - -**[3]:** * **AWS Lambda:** Use the (full) log stream name. - -**[4]:** It's recommended to set this attribute since e.g. too little memory can easily stop a Java AWS Lambda function from working correctly. On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` provides this information (which must be multiplied by 1,048,576). - -**[5]:** On some cloud providers, it may not be possible to determine the full ID at startup, +**[2]:** On some cloud providers, it may not be possible to determine the full ID at startup, so it may be necessary to set `cloud.resource_id` as a span attribute instead. The exact value to use for `cloud.resource_id` depends on the cloud provider. @@ -65,11 +51,25 @@ The following well-known definitions MUST be used if you set this attribute and with the resolved function version, as the same runtime instance may be invokable with multiple different aliases. * **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) -* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id) of the invoked function, +* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/rest/api/resources/resources/get-by-id) of the invoked function, *not* the function app, having the form `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/`. This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share a TracerProvider. + +**[3]:** * **AWS Lambda:** Use the (full) log stream name. + +**[4]:** It's recommended to set this attribute since e.g. too little memory can easily stop a Java AWS Lambda function from working correctly. On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` provides this information (which must be multiplied by 1,048,576). + +**[5]:** Depending on the cloud provider and platform, use: + +* **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) + (an integer represented as a decimal string). +* **Google Cloud Run (Services):** The [revision](https://cloud.google.com/run/docs/managing/revisions) + (i.e., the function name plus the revision suffix). +* **Google Cloud Functions:** The value of the + [`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically). +* **Azure Functions:** Not applicable. Do not set this attribute. Note: The resource attribute `faas.instance` differs from the span attribute `faas.invocation_id`. For more information see the [Semantic conventions for FaaS spans](/docs/faas/faas-spans.md#difference-between-invocation-and-instance). @@ -80,4 +80,4 @@ There are cases where a FaaS resource attribute is better applied as a span attribute instead. See the [FaaS trace conventions](/docs/faas/faas-spans.md) for more. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/host.md b/docs/resource/host.md index 96d7da4dea..4f39b8d508 100644 --- a/docs/resource/host.md +++ b/docs/resource/host.md @@ -6,29 +6,53 @@ **Description:** A host is defined as a computing instance. For example, physical servers, virtual machines, switches or disk array. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `host.id` | string | Unique host ID. For Cloud, this must be the instance_id assigned by the cloud provider. For non-containerized systems, this should be the `machine-id`. See the table below for the sources to use to determine the `machine-id` based on operating system. | `fdbf79e8af94cb7f9e8df36789187052` | Recommended | -| `host.name` | string | Name of the host. On Unix systems, it may contain what the hostname command returns, or the fully qualified hostname, or another name specified by the user. | `opentelemetry-test` | Recommended | -| `host.type` | string | Type of host. For Cloud, this must be the machine type. | `n1-standard-1` | Recommended | -| `host.arch` | string | The CPU architecture the host system is running on. | `amd64` | Recommended | -| `host.image.name` | string | Name of the VM image or OS install the host was instantiated from. | `infra-ami-eks-worker-node-7d4ec78312`; `CentOS-8-x86_64-1905` | Recommended | -| `host.image.id` | string | VM image ID or host OS image ID. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` | Recommended | -| `host.image.version` | string | The version string of the VM image or host OS as defined in [Version Attributes](README.md#version-attributes). | `0.1` | Recommended | - -`host.arch` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. - -| Value | Description | -|---|---| -| `amd64` | AMD64 | -| `arm32` | ARM32 | -| `arm64` | ARM64 | -| `ia64` | Itanium | -| `ppc32` | 32-bit PowerPC | -| `ppc64` | 64-bit PowerPC | -| `s390x` | IBM z/Architecture | -| `x86` | 32-bit x86 | +The `host.*` namespace SHOULD be exclusively used to capture resource attributes. +To report host metrics, the `system.*` namespace SHOULD be used. + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`host.arch`](/docs/attributes-registry/host.md) | string | The CPU architecture the host system is running on. | `amd64`; `arm32`; `arm64` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`host.id`](/docs/attributes-registry/host.md) | string | Unique host ID. For Cloud, this must be the instance_id assigned by the cloud provider. For non-containerized systems, this should be the `machine-id`. See the table below for the sources to use to determine the `machine-id` based on operating system. | `fdbf79e8af94cb7f9e8df36789187052` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`host.image.id`](/docs/attributes-registry/host.md) | string | VM image ID or host OS image ID. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`host.image.name`](/docs/attributes-registry/host.md) | string | Name of the VM image or OS install the host was instantiated from. | `infra-ami-eks-worker-node-7d4ec78312`; `CentOS-8-x86_64-1905` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`host.image.version`](/docs/attributes-registry/host.md) | string | The version string of the VM image or host OS as defined in [Version Attributes](/docs/resource/README.md#version-attributes). | `0.1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`host.name`](/docs/attributes-registry/host.md) | string | Name of the host. On Unix systems, it may contain what the hostname command returns, or the fully qualified hostname, or another name specified by the user. | `opentelemetry-test` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`host.type`](/docs/attributes-registry/host.md) | string | Type of host. For Cloud, this must be the machine type. | `n1-standard-1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`host.ip`](/docs/attributes-registry/host.md) | string[] | Available IP addresses of the host, excluding loopback interfaces. [1] | `192.168.1.140`; `fe80::abc2:4a28:737a:609e` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`host.mac`](/docs/attributes-registry/host.md) | string[] | Available MAC addresses of the host, excluding loopback interfaces. [2] | `AC-DE-48-23-45-67`; `AC-DE-48-23-45-67-01-9F` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** IPv4 Addresses MUST be specified in dotted-quad notation. IPv6 addresses MUST be specified in the [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952.html) format. + +**[2]:** MAC Addresses MUST be represented in [IEEE RA hexadecimal form](https://standards.ieee.org/wp-content/uploads/import/documents/tutorials/eui.pdf): as hyphen-separated octets in uppercase hexadecimal form from most to least significant. + +`host.arch` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `amd64` | AMD64 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `arm32` | ARM32 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `arm64` | ARM64 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ia64` | Itanium | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ppc32` | 32-bit PowerPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ppc64` | 64-bit PowerPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `s390x` | IBM z/Architecture | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `x86` | 32-bit x86 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**type:** `host.cpu` + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`host.cpu.cache.l2.size`](/docs/attributes-registry/host.md) | int | The amount of level 2 memory cache available to the processor (in Bytes). | `12288000` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`host.cpu.family`](/docs/attributes-registry/host.md) | string | Family or generation of the CPU. | `6`; `PA-RISC 1.1e` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`host.cpu.model.id`](/docs/attributes-registry/host.md) | string | Model identifier. It provides more granular information about the CPU, distinguishing it from other CPUs within the same family. | `6`; `9000/778/B180L` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`host.cpu.model.name`](/docs/attributes-registry/host.md) | string | Model designation of the processor. | `11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`host.cpu.stepping`](/docs/attributes-registry/host.md) | string | Stepping or core revisions. | `1`; `r1p1` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`host.cpu.vendor.id`](/docs/attributes-registry/host.md) | string | Processor manufacturer identifier. A maximum 12-character string. [1] | `GenuineIntel` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** [CPUID](https://wiki.osdev.org/CPUID) command returns the vendor ID string in EBX, EDX and ECX registers. Writing these to memory in this order results in a 12-character string. ## Collecting host.id from non-containerized systems @@ -39,12 +63,12 @@ When collecting `host.id` for non-containerized systems non-privileged lookups of the machine id are preferred. SDK detector implementations MUST use the sources listed below to obtain the machine id. -| OS | Primary | Fallback | -|---------|-------------------------------------------------------------------------------------|----------------------------------------| -| Linux | contents of `/etc/machine-id` | contents of `/var/lib/dbus/machine-id` | -| BSD | contents of `/etc/hostid` | output of `kenv -q smbios.system.uuid` | -| MacOS | `IOPlatformUUID` line from the output of `ioreg -rd1 -c "IOPlatformExpertDevice"` | - | -| Windows | `MachineGuid` from registry `HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Cryptography` | - | +| OS | Primary | Fallback | +|---------|-----------------------------------------------------------------------------------|----------------------------------------| +| Linux | contents of `/etc/machine-id` | contents of `/var/lib/dbus/machine-id` | +| BSD | contents of `/etc/hostid` | output of `kenv -q smbios.system.uuid` | +| MacOS | `IOPlatformUUID` line from the output of `ioreg -rd1 -c "IOPlatformExpertDevice"` | - | +| Windows | `MachineGuid` from registry `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography` | - | ### Privileged Machine ID Lookup @@ -57,4 +81,4 @@ detector implementations MUST not collect `host.id` from privileged sources. If privileged lookup of `host.id` is required, the value should be injected via the `OTEL_RESOURCE_ATTRIBUTES` environment variable. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/k8s.md b/docs/resource/k8s.md index 6aada5e772..0ee64504f5 100644 --- a/docs/resource/k8s.md +++ b/docs/resource/k8s.md @@ -22,12 +22,12 @@ Kubernetes object, but "name" is usually more user friendly so can be also set. **Description:** A Kubernetes Cluster. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.cluster.name` | string | The name of the cluster. | `opentelemetry-cluster` | Recommended | -| `k8s.cluster.uid` | string | A pseudo-ID for the cluster, set to the UID of the `kube-system` namespace. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`k8s.cluster.name`](../attributes-registry/k8s.md) | string | The name of the cluster. | `opentelemetry-cluster` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`k8s.cluster.uid`](../attributes-registry/k8s.md) | string | A pseudo-ID for the cluster, set to the UID of the `kube-system` namespace. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** K8s does not have support for obtaining a cluster ID. If this is ever +**[1]:** K8s doesn't have support for obtaining a cluster ID. If this is ever added, we will recommend collecting the `k8s.cluster.uid` through the official APIs. In the meantime, we are able to use the `uid` of the `kube-system` namespace as a proxy for cluster ID. Read on for the @@ -58,10 +58,10 @@ conflict. **Description:** A Kubernetes Node. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.node.name` | string | The name of the Node. | `node-1` | Recommended | -| `k8s.node.uid` | string | The UID of the Node. | `1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`k8s.node.name`](../attributes-registry/k8s.md) | string | The name of the Node. | `node-1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`k8s.node.uid`](../attributes-registry/k8s.md) | string | The UID of the Node. | `1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## Namespace @@ -74,9 +74,9 @@ a namespace, but not across namespaces. **Description:** A Kubernetes Namespace. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.namespace.name` | string | The name of the namespace that the pod is running in. | `default` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`k8s.namespace.name`](../attributes-registry/k8s.md) | string | The name of the namespace that the pod is running in. | `default` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## Pod @@ -89,10 +89,12 @@ containers on your cluster. **Description:** A Kubernetes Pod object. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.pod.uid` | string | The UID of the Pod. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | -| `k8s.pod.name` | string | The name of the Pod. | `opentelemetry-pod-autoconf` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`k8s.pod.label.`](../attributes-registry/k8s.md) | string | The label key-value pairs placed on the Pod, the `` being the label name, the value being the label value. | `k8s.pod.label.app=my-app`; `k8s.pod.label.mycompany.io/arch=x64`; `k8s.pod.label.data=` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`k8s.pod.name`](../attributes-registry/k8s.md) | string | The name of the Pod. | `opentelemetry-pod-autoconf` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`k8s.pod.uid`](../attributes-registry/k8s.md) | string | The UID of the Pod. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`k8s.pod.annotation.`](../attributes-registry/k8s.md) | string | The annotation key-value pairs placed on the Pod, the `` being the annotation name, the value being the annotation value. | `k8s.pod.annotation.kubernetes.io/enforce-mountable-secrets=true`; `k8s.pod.annotation.mycompany.io/arch=x64`; `k8s.pod.annotation.data=` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## Container @@ -109,10 +111,11 @@ to a running container. **Description:** A container in a [PodTemplate](https://kubernetes.io/docs/concepts/workloads/pods/#pod-templates). -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.container.name` | string | The name of the Container from Pod specification, must be unique within a Pod. Container runtime usually uses different globally unique name (`container.name`). | `redis` | Recommended | -| `k8s.container.restart_count` | int | Number of times the container was restarted. This attribute can be used to identify a particular container (running or stopped) within a container spec. | `0`; `2` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`k8s.container.name`](../attributes-registry/k8s.md) | string | The name of the Container from Pod specification, must be unique within a Pod. Container runtime usually uses different globally unique name (`container.name`). | `redis` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`k8s.container.restart_count`](../attributes-registry/k8s.md) | int | Number of times the container was restarted. This attribute can be used to identify a particular container (running or stopped) within a container spec. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`k8s.container.status.last_terminated_reason`](../attributes-registry/k8s.md) | string | Last terminated reason of the Container. | `Evicted`; `Error` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## ReplicaSet @@ -125,10 +128,10 @@ any given time. **Description:** A Kubernetes ReplicaSet object. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.replicaset.uid` | string | The UID of the ReplicaSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | -| `k8s.replicaset.name` | string | The name of the ReplicaSet. | `opentelemetry` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`k8s.replicaset.name`](../attributes-registry/k8s.md) | string | The name of the ReplicaSet. | `opentelemetry` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`k8s.replicaset.uid`](../attributes-registry/k8s.md) | string | The UID of the ReplicaSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## Deployment @@ -142,10 +145,10 @@ distributed among the nodes of a cluster. **Description:** A Kubernetes Deployment object. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.deployment.uid` | string | The UID of the Deployment. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | -| `k8s.deployment.name` | string | The name of the Deployment. | `opentelemetry` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`k8s.deployment.name`](../attributes-registry/k8s.md) | string | The name of the Deployment. | `opentelemetry` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`k8s.deployment.uid`](../attributes-registry/k8s.md) | string | The UID of the Deployment. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## StatefulSet @@ -158,10 +161,10 @@ about the ordering and uniqueness of these Pods. **Description:** A Kubernetes StatefulSet object. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.statefulset.uid` | string | The UID of the StatefulSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | -| `k8s.statefulset.name` | string | The name of the StatefulSet. | `opentelemetry` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`k8s.statefulset.name`](../attributes-registry/k8s.md) | string | The name of the StatefulSet. | `opentelemetry` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`k8s.statefulset.uid`](../attributes-registry/k8s.md) | string | The UID of the StatefulSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## DaemonSet @@ -173,10 +176,10 @@ A DaemonSet ensures that all (or some) Nodes run a copy of a Pod. **Description:** A Kubernetes DaemonSet object. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.daemonset.uid` | string | The UID of the DaemonSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | -| `k8s.daemonset.name` | string | The name of the DaemonSet. | `opentelemetry` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`k8s.daemonset.name`](../attributes-registry/k8s.md) | string | The name of the DaemonSet. | `opentelemetry` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`k8s.daemonset.uid`](../attributes-registry/k8s.md) | string | The UID of the DaemonSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## Job @@ -189,10 +192,10 @@ successfully terminate. **Description:** A Kubernetes Job object. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.job.uid` | string | The UID of the Job. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | -| `k8s.job.name` | string | The name of the Job. | `opentelemetry` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`k8s.job.name`](../attributes-registry/k8s.md) | string | The name of the Job. | `opentelemetry` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`k8s.job.uid`](../attributes-registry/k8s.md) | string | The UID of the Job. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## CronJob @@ -204,10 +207,10 @@ A CronJob creates Jobs on a repeating schedule. **Description:** A Kubernetes CronJob object. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.cronjob.uid` | string | The UID of the CronJob. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | -| `k8s.cronjob.name` | string | The name of the CronJob. | `opentelemetry` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`k8s.cronjob.name`](../attributes-registry/k8s.md) | string | The name of the CronJob. | `opentelemetry` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`k8s.cronjob.uid`](../attributes-registry/k8s.md) | string | The UID of the CronJob. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/os.md b/docs/resource/os.md index 2b73acea08..6b638d07b7 100644 --- a/docs/resource/os.md +++ b/docs/resource/os.md @@ -8,29 +8,30 @@ In case of virtualized environments, this is the operating system as it is observed by the process, i.e., the virtualized guest rather than the underlying host. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `os.type` | string | The operating system type. | `windows` | Required | -| `os.description` | string | Human readable (not intended to be parsed) OS version information, like e.g. reported by `ver` or `lsb_release -a` commands. | `Microsoft Windows [Version 10.0.18363.778]`; `Ubuntu 18.04.1 LTS` | Recommended | -| `os.name` | string | Human readable operating system name. | `iOS`; `Android`; `Ubuntu` | Recommended | -| `os.version` | string | The version string of the operating system as defined in [Version Attributes](/docs/resource/README.md#version-attributes). | `14.2.1`; `18.04.1` | Recommended | - -`os.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. - -| Value | Description | -|---|---| -| `windows` | Microsoft Windows | -| `linux` | Linux | -| `darwin` | Apple Darwin | -| `freebsd` | FreeBSD | -| `netbsd` | NetBSD | -| `openbsd` | OpenBSD | -| `dragonflybsd` | DragonFly BSD | -| `hpux` | HP-UX (Hewlett Packard Unix) | -| `aix` | AIX (Advanced Interactive eXecutive) | -| `solaris` | SunOS, Oracle Solaris | -| `z_os` | IBM z/OS | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`os.type`](/docs/attributes-registry/os.md) | string | The operating system type. | `windows`; `linux`; `darwin` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`os.build_id`](/docs/attributes-registry/os.md) | string | Unique identifier for a particular build or compilation of the operating system. | `TQ3C.230805.001.B2`; `20E247`; `22621` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`os.description`](/docs/attributes-registry/os.md) | string | Human readable (not intended to be parsed) OS version information, like e.g. reported by `ver` or `lsb_release -a` commands. | `Microsoft Windows [Version 10.0.18363.778]`; `Ubuntu 18.04.1 LTS` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`os.name`](/docs/attributes-registry/os.md) | string | Human readable operating system name. | `iOS`; `Android`; `Ubuntu` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`os.version`](/docs/attributes-registry/os.md) | string | The version string of the operating system as defined in [Version Attributes](/docs/resource/README.md#version-attributes). | `14.2.1`; `18.04.1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`os.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `windows` | Microsoft Windows | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `linux` | Linux | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `darwin` | Apple Darwin | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `freebsd` | FreeBSD | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `netbsd` | NetBSD | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `openbsd` | OpenBSD | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dragonflybsd` | DragonFly BSD | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hpux` | HP-UX (Hewlett Packard Unix) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aix` | AIX (Advanced Interactive eXecutive) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `solaris` | SunOS, Oracle Solaris | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `z_os` | IBM z/OS | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/process.md b/docs/resource/process.md index 388f26129c..86081e0f9e 100644 --- a/docs/resource/process.md +++ b/docs/resource/process.md @@ -7,14 +7,15 @@ - [Process](#process) + - [Selecting process attributes](#selecting-process-attributes) - [Process runtimes](#process-runtimes) - * [Erlang Runtimes](#erlang-runtimes) - * [Go Runtimes](#go-runtimes) - * [Java runtimes](#java-runtimes) - * [JavaScript runtimes](#javascript-runtimes) - * [.NET Runtimes](#net-runtimes) - * [Python Runtimes](#python-runtimes) - * [Ruby Runtimes](#ruby-runtimes) + - [Erlang Runtimes](#erlang-runtimes) + - [Go Runtimes](#go-runtimes) + - [Java runtimes](#java-runtimes) + - [JavaScript runtimes](#javascript-runtimes) + - [.NET Runtimes](#net-runtimes) + - [Python Runtimes](#python-runtimes) + - [Ruby Runtimes](#ruby-runtimes) @@ -25,34 +26,42 @@ **Description:** An operating system process. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `process.pid` | int | Process identifier (PID). | `1234` | Recommended | -| `process.parent_pid` | int | Parent Process identifier (PID). | `111` | Recommended | -| `process.executable.name` | string | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | Conditionally Required: See alternative attributes below. | -| `process.executable.path` | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | Conditionally Required: See alternative attributes below. | -| `process.command` | string | The command used to launch the process (i.e. the command name). On Linux based systems, can be set to the zeroth string in `proc/[pid]/cmdline`. On Windows, can be set to the first parameter extracted from `GetCommandLineW`. | `cmd/otelcol` | Conditionally Required: See alternative attributes below. | -| `process.command_line` | string | The full command used to launch the process as a single string representing the full command. On Windows, can be set to the result of `GetCommandLineW`. Do not set this if you have to assemble it just for monitoring; use `process.command_args` instead. | `C:\cmd\otecol --config="my directory\config.yaml"` | Conditionally Required: See alternative attributes below. | -| `process.command_args` | string[] | All the command arguments (including the command/executable itself) as received by the process. On Linux-based systems (and some other Unixoid systems supporting procfs), can be set according to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. For libc-based executables, this would be the full argv vector passed to `main`. | `[cmd/otecol, --config=config.yaml]` | Conditionally Required: See alternative attributes below. | -| `process.owner` | string | The username of the user that owns the process. | `root` | Recommended | - -**Additional attribute requirements:** At least one of the following sets of attributes is required: - -* `process.executable.name` -* `process.executable.path` -* `process.command` -* `process.command_line` -* `process.command_args` +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`process.command`](/docs/attributes-registry/process.md) | string | The command used to launch the process (i.e. the command name). On Linux based systems, can be set to the zeroth string in `proc/[pid]/cmdline`. On Windows, can be set to the first parameter extracted from `GetCommandLineW`. | `cmd/otelcol` | `Conditionally Required` [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.command_args`](/docs/attributes-registry/process.md) | string[] | All the command arguments (including the command/executable itself) as received by the process. On Linux-based systems (and some other Unixoid systems supporting procfs), can be set according to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. For libc-based executables, this would be the full argv vector passed to `main`. | `cmd/otecol`; `--config=config.yaml` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.command_line`](/docs/attributes-registry/process.md) | string | The full command used to launch the process as a single string representing the full command. On Windows, can be set to the result of `GetCommandLineW`. Do not set this if you have to assemble it just for monitoring; use `process.command_args` instead. | `C:\cmd\otecol --config="my directory\config.yaml"` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.executable.name`](/docs/attributes-registry/process.md) | string | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.executable.path`](/docs/attributes-registry/process.md) | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.owner`](/docs/attributes-registry/process.md) | string | The username of the user that owns the process. | `root` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.parent_pid`](/docs/attributes-registry/process.md) | int | Parent Process identifier (PPID). | `111` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.pid`](/docs/attributes-registry/process.md) | int | Process identifier (PID). | `1234` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** See [Selecting process attributes](#selecting-process-attributes) for details. + +**[2]:** See [Selecting process attributes](#selecting-process-attributes) for details. + +**[3]:** See [Selecting process attributes](#selecting-process-attributes) for details. + +**[4]:** See [Selecting process attributes](#selecting-process-attributes) for details. + +**[5]:** See [Selecting process attributes](#selecting-process-attributes) for details. +### Selecting process attributes + +At least one of the following attributes is required: + +* [`process.executable.name`](../attributes-registry/process.md) +* [`process.executable.path`](../attributes-registry/process.md) +* [`process.command`](../attributes-registry/process.md) +* [`process.command_line`](../attributes-registry/process.md) +* [`process.command_args`](../attributes-registry/process.md) + Between `process.command_args` and `process.command_line`, usually `process.command_args` should be preferred. On Windows and other systems where the native format of process commands is a single string, `process.command_line` can additionally (or instead) be used. -For backwards compatibility with older versions of this semantic convention, -it is possible but deprecated to use an array as type for `process.command_line`. -In that case it MUST be interpreted as if it was `process.command_args`. - ## Process runtimes **type:** `process.runtime` @@ -60,11 +69,11 @@ In that case it MUST be interpreted as if it was `process.command_args`. **Description:** The single (language) runtime instance which is monitored. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `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` | Recommended | -| `process.runtime.version` | string | The version of the runtime of this process, as returned by the runtime without modification. | `14.0.2` | Recommended | -| `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` | Recommended | +| 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.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) | How to set these attributes for particular runtime kinds is described in the following subsections. @@ -85,7 +94,7 @@ Example: ### Go Runtimes -Go Runtimes should fill in the as follows: +Go Runtimes SHOULD fill in the as follows: - `process.runtime.name` - Fill in an interpretation of Go's [`runtime.Compiler`](https://pkg.go.dev/runtime#Compiler) constant, according to the following rule: If the value is `gc`, fill in `go`. Otherwise, fill in the exact value of `runtime.Compiler`. @@ -94,7 +103,7 @@ Go Runtimes should fill in the as follows: ```go import "runtime" - + func getRuntimeName() string { if runtime.Compiler == "gc" { return "go" @@ -116,7 +125,7 @@ Examples for some Go compilers/runtimes: ### Java runtimes -Java instrumentation should fill in the values by copying from system properties. +Java instrumentation SHOULD fill in the values by copying from system properties. - `process.runtime.name` - Fill in the value of `java.runtime.name` as is - `process.runtime.version` - Fill in the value of `java.runtime.version` as is @@ -138,7 +147,7 @@ Examples for some Java runtimes ### JavaScript runtimes -JavaScript instrumentation should fill in the values by copying from built-in runtime constants. +JavaScript instrumentation SHOULD fill in the values by copying from built-in runtime constants. - `process.runtime.name`: - When the runtime is Node.js, fill in the constant value `nodejs`. @@ -156,17 +165,31 @@ Examples for some JavaScript runtimes ### .NET Runtimes -TODO(): Confirm the contents here +.NET instrumentation SHOULD fill in the values by following values: -| Value | Description | -| --- | --- | -| `dotnet-core` | .NET Core, .NET 5+ | -| `dotnet-framework` | .NET Framework | -| `mono` | Mono | +- `process.runtime.name` - Fill in the value by the name of runtime. +- `process.runtime.version` - Fill in the value of `System.Environment.Version` for .NET, + determine version based on the [registry values](https://learn.microsoft.com/en-us/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed#query-the-registry-using-code) + for .NET Framework +- `process.runtime.description` - Fill in the values of `System.Runtime.InteropServices.RuntimeInformation.FrameworkDescription`. + +`process.runtime.name` has the following list of well-known values. If one of them applies, then the respective value SHOULD be used, otherwise a custom value SHOULD be used. + +- .NET Framework +- .NET +- .NET Core +- .NET Native + +Examples for some .NET runtimes + +| Name | `process.runtime.name` | `process.runtime.version` | `process.runtime.description` | +| --- | --- | --- | --- | +| .NET Framework | .NET Framework | 4.8 | .NET Framework 4.8.9195.0 | +| .NET | .NET | 7.0.14 | .NET 7.0.14 | ### Python Runtimes -Python instrumentation should fill in the values as follows: +Python instrumentation SHOULD fill in the values as follows: - `process.runtime.name` - Fill in the value of [`sys.implementation.name`][py_impl] @@ -207,7 +230,7 @@ Pypy provided a CPython-compatible version in `sys.implementation.version` inste ### Ruby Runtimes -Ruby instrumentation should fill in the values by copying from built-in runtime constants. +Ruby instrumentation SHOULD fill in the values by copying from built-in runtime constants. - `process.runtime.name` - Fill in the value of `RUBY_ENGINE` as is - `process.runtime.version` - Fill in the value of `RUBY_VERSION` as is @@ -220,4 +243,4 @@ Examples for some Ruby runtimes | MRI | ruby | 2.7.1 | ruby 2.7.1p83 (2020-03-31 revision a0c7c23c9c) [x86_64-darwin19] | | TruffleRuby | truffleruby | 2.6.2 | truffleruby (Shopify) 20.0.0-dev-92ed3059, like ruby 2.6.2, GraalVM CE Native [x86_64-darwin] | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/resource/webengine.md b/docs/resource/webengine.md index 8b3a0985c7..0a7b282450 100644 --- a/docs/resource/webengine.md +++ b/docs/resource/webengine.md @@ -7,11 +7,11 @@ **Description:** Resource describing the packaged software running the application code. Web engines are typically executed using process.runtime. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `webengine.name` | string | The name of the web engine. | `WildFly` | Required | -| `webengine.version` | string | The version of the web engine. | `21.0.0` | Recommended | -| `webengine.description` | string | Additional description of the web engine (e.g. detailed version and edition information). | `WildFly Full 21.0.0.Final (WildFly Core 13.0.1.Final) - 2.2.2.Final` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`webengine.name`](/docs/attributes-registry/webengine.md) | string | The name of the web engine. | `WildFly` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`webengine.description`](/docs/attributes-registry/webengine.md) | string | Additional description of the web engine (e.g. detailed version and edition information). | `WildFly Full 21.0.0.Final (WildFly Core 13.0.1.Final) - 2.2.2.Final` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`webengine.version`](/docs/attributes-registry/webengine.md) | string | The version of the web engine. | `21.0.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | Information describing the web engine SHOULD be captured using the values acquired from the API provided by the web engine, preferably during runtime, to avoid maintenance burden on engine version upgrades. As an example - Java engines are often but not always packaged as application servers. For Java application servers supporting Servlet API the required information MAY be captured by invoking `ServletContext.getServerInfo()` during runtime and parsing the result. @@ -23,4 +23,4 @@ The situations where there are multiple candidates, it is up to instrumentation * Either Apache HTTP Server or `mod_wsgi` MAY be chosen as `webengine`, depending on the decision made by the instrumentation authors. * Django SHOULD NOT be set as an `webengine` as the required information is already available in instrumentation library and setting this into `webengine` would duplicate the information. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/rpc/README.md b/docs/rpc/README.md index 81105afb30..685e73c9b3 100644 --- a/docs/rpc/README.md +++ b/docs/rpc/README.md @@ -1,7 +1,7 @@ @@ -23,4 +23,8 @@ Technology specific semantic conventions are defined for the following RPC syste * [gRPC](grpc.md): Semantic Conventions for *gRPC*. * [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +Specifications defined by maintainers of RPC systems: + +* [gRPC](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md): Semantic Conventions for *gRPC*. + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md index f383bf7703..4ef1dd0660 100644 --- a/docs/rpc/connect-rpc.md +++ b/docs/rpc/connect-rpc.md @@ -16,47 +16,43 @@ described on this page. Below is a table of attributes that SHOULD be included on client and server Connect RPC measurements. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `rpc.connect_rpc.error_code` | string | The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. | `cancelled` | Conditionally Required: [1] | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.connect_rpc.error_code`](/docs/attributes-registry/rpc.md) | string | The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. | `cancelled`; `unknown`; `invalid_argument` | `Conditionally Required` [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.connect_rpc.request.metadata.`](/docs/attributes-registry/rpc.md) | string[] | Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. [2] | `rpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.connect_rpc.response.metadata.`](/docs/attributes-registry/rpc.md) | string[] | Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. [3] | `rpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** If response is not successful and if error code available. -`rpc.connect_rpc.error_code` MUST be one of the following: - -| Value | Description | -|---|---| -| `cancelled` | cancelled | -| `unknown` | unknown | -| `invalid_argument` | invalid_argument | -| `deadline_exceeded` | deadline_exceeded | -| `not_found` | not_found | -| `already_exists` | already_exists | -| `permission_denied` | permission_denied | -| `resource_exhausted` | resource_exhausted | -| `failed_precondition` | failed_precondition | -| `aborted` | aborted | -| `out_of_range` | out_of_range | -| `unimplemented` | unimplemented | -| `internal` | internal | -| `unavailable` | unavailable | -| `data_loss` | data_loss | -| `unauthenticated` | unauthenticated | +**[2]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + +**[3]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + +`rpc.connect_rpc.error_code` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `cancelled` | cancelled | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unknown` | unknown | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `invalid_argument` | invalid_argument | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `deadline_exceeded` | deadline_exceeded | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `not_found` | not_found | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `already_exists` | already_exists | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `permission_denied` | permission_denied | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `resource_exhausted` | resource_exhausted | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `failed_precondition` | failed_precondition | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aborted` | aborted | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `out_of_range` | out_of_range | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unimplemented` | unimplemented | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `internal` | internal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unavailable` | unavailable | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `data_loss` | data_loss | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unauthenticated` | unauthenticated | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## Connect RPC Status -If `rpc.connect_rpc.error_code` is set, [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#set-status) MUST be set to `Error` and left unset in all other cases. +If `rpc.connect_rpc.error_code` is set, [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/trace/api.md#set-status) MUST be set to `Error` and left unset in all other cases. -## Connect RPC Request and Response Metadata - -| Attribute | Type | Description | Examples | Requirement Level | -|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|-------------------| -| `rpc.connect_rpc.request.metadata.` | string[] | Connect request metadata, `` being the normalized Connect Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]` | Optional | -| `rpc.connect_rpc.response.metadata.` | string[] | Connect response metadata, `` being the normalized Connect Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Optional | - -**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. -Including all request/response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. - -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md index c5f140bf6f..c2c31ba541 100644 --- a/docs/rpc/grpc.md +++ b/docs/rpc/grpc.md @@ -16,41 +16,47 @@ described on this page. Below is a table of attributes that SHOULD be included on client and server gRPC measurements. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `rpc.grpc.status_code` | int | The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. | `0` | Required | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.grpc.status_code`](/docs/attributes-registry/rpc.md) | int | The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. | `0`; `1`; `2` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.grpc.request.metadata.`](/docs/attributes-registry/rpc.md) | string[] | gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [1] | `rpc.grpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.grpc.response.metadata.`](/docs/attributes-registry/rpc.md) | string[] | gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [2] | `rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`rpc.grpc.status_code` MUST be one of the following: +**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. -| Value | Description | -|---|---| -| `0` | OK | -| `1` | CANCELLED | -| `2` | UNKNOWN | -| `3` | INVALID_ARGUMENT | -| `4` | DEADLINE_EXCEEDED | -| `5` | NOT_FOUND | -| `6` | ALREADY_EXISTS | -| `7` | PERMISSION_DENIED | -| `8` | RESOURCE_EXHAUSTED | -| `9` | FAILED_PRECONDITION | -| `10` | ABORTED | -| `11` | OUT_OF_RANGE | -| `12` | UNIMPLEMENTED | -| `13` | INTERNAL | -| `14` | UNAVAILABLE | -| `15` | DATA_LOSS | -| `16` | UNAUTHENTICATED | +**[2]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + +`rpc.grpc.status_code` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `0` | OK | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `1` | CANCELLED | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `2` | UNKNOWN | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `3` | INVALID_ARGUMENT | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `4` | DEADLINE_EXCEEDED | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `5` | NOT_FOUND | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `6` | ALREADY_EXISTS | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `7` | PERMISSION_DENIED | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `8` | RESOURCE_EXHAUSTED | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `9` | FAILED_PRECONDITION | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `10` | ABORTED | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `11` | OUT_OF_RANGE | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `12` | UNIMPLEMENTED | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `13` | INTERNAL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `14` | UNAVAILABLE | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `15` | DATA_LOSS | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `16` | UNAUTHENTICATED | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## gRPC Status The table below describes when -the [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#set-status) MUST be set +the [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/trace/api.md#set-status) MUST be set to `Error` or remain unset depending on the [gRPC status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) -and [Span Kind](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#spankind). +and [Span Kind](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/trace/api.md#spankind). | gRPC Status Code | `SpanKind.SERVER` Span Status | `SpanKind.CLIENT` Span Status | |---|---|---| @@ -72,14 +78,4 @@ and [Span Kind](https://github.com/open-telemetry/opentelemetry-specification/tr | DATA_LOSS | `Error` | `Error` | | UNAUTHENTICATED | unset | `Error` | -## gRPC Request and Response Metadata - -| Attribute | Type | Description | Examples | Requirement Level | -|-------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|-------------------| -| `rpc.grpc.request.metadata.` | string[] | gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]` | Opt-In | -| `rpc.grpc.response.metadata.` | string[] | gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Opt-In | - -**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. -Including all request/response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. - -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/rpc/json-rpc.md b/docs/rpc/json-rpc.md index 3c26a8eeb9..c31b17bdd8 100644 --- a/docs/rpc/json-rpc.md +++ b/docs/rpc/json-rpc.md @@ -14,16 +14,16 @@ described on this page. `rpc.system` MUST be set to `"jsonrpc"`. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `rpc.jsonrpc.version` | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 does not specify this, the value can be omitted. | `2.0`; `1.0` | Conditionally Required: If other than the default version (`1.0`) | -| `rpc.jsonrpc.request_id` | string | `id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. | `10`; `request-7`; `` | Recommended | -| `rpc.jsonrpc.error_code` | int | `error.code` property of response if it is an error response. | `-32700`; `100` | Conditionally Required: If response is not successful. | -| `rpc.jsonrpc.error_message` | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | Recommended | -| [`rpc.method`](rpc-spans.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [1] | `exampleMethod` | Required | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [1] | `exampleMethod` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.jsonrpc.error_code`](/docs/attributes-registry/rpc.md) | int | `error.code` property of response if it is an error response. | `-32700`; `100` | `Conditionally Required` If response is not successful. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.jsonrpc.version`](/docs/attributes-registry/rpc.md) | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. | `2.0`; `1.0` | `Conditionally Required` If other than the default version (`1.0`) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.jsonrpc.error_message`](/docs/attributes-registry/rpc.md) | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.jsonrpc.request_id`](/docs/attributes-registry/rpc.md) | string | `id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. | `10`; `request-7`; `` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** This is always required for jsonrpc. See the note in the general RPC conventions for more information. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index aaa3647ad3..5c892f8245 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -17,10 +17,20 @@ metrics can be filtered for finer grain analysis. - [Metric instruments](#metric-instruments) - * [RPC Server](#rpc-server) - * [RPC Client](#rpc-client) + - [RPC Server](#rpc-server) + - [Metric: `rpc.server.duration`](#metric-rpcserverduration) + - [Metric: `rpc.server.request.size`](#metric-rpcserverrequestsize) + - [Metric: `rpc.server.response.size`](#metric-rpcserverresponsesize) + - [Metric: `rpc.server.requests_per_rpc`](#metric-rpcserverrequests_per_rpc) + - [Metric: `rpc.server.responses_per_rpc`](#metric-rpcserverresponses_per_rpc) + - [RPC Client](#rpc-client) + - [Metric: `rpc.client.duration`](#metric-rpcclientduration) + - [Metric: `rpc.client.request.size`](#metric-rpcclientrequestsize) + - [Metric: `rpc.client.response.size`](#metric-rpcclientresponsesize) + - [Metric: `rpc.client.requests_per_rpc`](#metric-rpcclientrequests_per_rpc) + - [Metric: `rpc.client.responses_per_rpc`](#metric-rpcclientresponses_per_rpc) - [Attributes](#attributes) - * [Service name](#service-name) + - [Service name](#service-name) - [Semantic Conventions for specific RPC technologies](#semantic-conventions-for-specific-rpc-technologies) @@ -30,25 +40,26 @@ metrics can be filtered for finer grain analysis. > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/rpc-metrics.md) > (or prior): > -> * SHOULD NOT change the version of the networking attributes that they emit +> * SHOULD NOT change the version of the networking conventions that they emit > until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in RPC instrumentations). +> include stabilization of a core set of networking conventions which are also used +> in RPC instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable networking attributes, -> and stop emitting the old experimental networking attributes +> * `http` - emit the new, stable networking conventions, +> and stop emitting the old experimental networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable networking attributes, +> * `http/dup` - emit both the old and the stable networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental networking attributes +> emitting whatever version of the old experimental networking conventions > the instrumentation was emitting previously. +> * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). +> for at least six months after it starts emitting both sets of conventions. +> * SHOULD drop the environment variable in the next major version. ## Metric instruments @@ -59,74 +70,205 @@ MUST be of the specified type and units. ### RPC Server -Below is a table of RPC server metric instruments. +Below is a list of RPC server metric instruments. -| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | Status | Streaming | -|------|------------|------|-------------------------------------------|-------------|--------|-----------| -| `rpc.server.duration` | Histogram | milliseconds | `ms` | measures duration of inbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. | -| `rpc.server.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch | -| `rpc.server.response.size` | Histogram | Bytes | `By` | measures size of RPC response messages (uncompressed) | Optional | Recorded per response in a streaming batch | -| `rpc.server.requests_per_rpc` | Histogram | count | `{count}` | measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | -| `rpc.server.responses_per_rpc` | Histogram | count | `{count}` | measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | +#### Metric: `rpc.server.duration` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `rpc.server.duration` | Histogram | `ms` | Measures the duration of inbound RPC. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** While streaming RPCs may record this metric as start-of-batch +to end-of-batch, it's hard to interpret in practice. + +**Streaming**: N/A. + + +#### Metric: `rpc.server.request.size` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `rpc.server.request.size` | Histogram | `By` | Measures the size of RPC request messages (uncompressed). [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** **Streaming**: Recorded per message in a streaming batch + + +#### Metric: `rpc.server.response.size` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `rpc.server.response.size` | Histogram | `By` | Measures the size of RPC response messages (uncompressed). [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** **Streaming**: Recorded per response in a streaming batch + + +#### Metric: `rpc.server.requests_per_rpc` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `rpc.server.requests_per_rpc` | Histogram | `{count}` | Measures the number of messages received per RPC. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Should be 1 for all non-streaming RPCs. + +**Streaming** : This metric is required for server and client streaming RPCs + + +#### Metric: `rpc.server.responses_per_rpc` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `rpc.server.responses_per_rpc` | Histogram | `{count}` | Measures the number of messages sent per RPC. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Should be 1 for all non-streaming RPCs. + +**Streaming**: This metric is required for server and client streaming RPCs + ### RPC Client -Below is a table of RPC client metric instruments. These apply to traditional -RPC usage, not streaming RPCs. +Below is a list of RPC client metric instruments. +These apply to traditional RPC usage, not streaming RPCs. + +#### Metric: `rpc.client.duration` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `rpc.client.duration` | Histogram | `ms` | Measures the duration of outbound RPC. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** While streaming RPCs may record this metric as start-of-batch +to end-of-batch, it's hard to interpret in practice. -| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | Status | Streaming | -|------|------------|------|-------------------------------------------|-------------|--------|-----------| -| `rpc.client.duration` | Histogram | milliseconds | `ms` | measures duration of outbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. | -| `rpc.client.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch | -| `rpc.client.response.size` | Histogram | Bytes | `By` | measures size of RPC response messages (uncompressed) | Optional | Recorded per message in a streaming batch | -| `rpc.client.requests_per_rpc` | Histogram | count | `{count}` | measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | -| `rpc.client.responses_per_rpc` | Histogram | count | `{count}` | measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | +**Streaming**: N/A. + + +#### Metric: `rpc.client.request.size` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `rpc.client.request.size` | Histogram | `By` | Measures the size of RPC request messages (uncompressed). [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** **Streaming**: Recorded per message in a streaming batch + + +#### Metric: `rpc.client.response.size` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `rpc.client.response.size` | Histogram | `By` | Measures the size of RPC response messages (uncompressed). [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** **Streaming**: Recorded per response in a streaming batch + + +#### Metric: `rpc.client.requests_per_rpc` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `rpc.client.requests_per_rpc` | Histogram | `{count}` | Measures the number of messages received per RPC. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Should be 1 for all non-streaming RPCs. + +**Streaming**: This metric is required for server and client streaming RPCs + + +#### Metric: `rpc.client.responses_per_rpc` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `rpc.client.responses_per_rpc` | Histogram | `{count}` | Measures the number of messages sent per RPC. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Should be 1 for all non-streaming RPCs. + +**Streaming**: This metric is required for server and client streaming RPCs + ## Attributes Below is a table of attributes that SHOULD be included on client and server RPC measurements. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`rpc.system`](rpc-spans.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | -| [`rpc.service`](rpc-spans.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended | -| [`rpc.method`](rpc-spans.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended | -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/attributes.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | -| [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: See below | -| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | See below | -| [`server.socket.port`](../general/attributes.md) | int | Physical server port. | `16456` | Recommended: [4] | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.system`](/docs/attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc`; `java_rmi`; `dotnet_wcf` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.type`](/docs/attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | `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) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). +**[1]:** The value SHOULD be normalized to lowercase. -**[2]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. -**[3]:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. +**[2]:** The value SHOULD be normalized to lowercase. -**[4]:** If different than `server.port` and if `server.socket.address` is set. +**[3]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). -**Additional attribute requirements:** At least one of the following sets of attributes is required: +**[4]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). -* [`server.socket.address`](../general/attributes.md) -* [`server.address`](../general/attributes.md) +**[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. -`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -| Value | Description | -|---|---| -| `grpc` | gRPC | -| `java_rmi` | Java RMI | -| `dotnet_wcf` | .NET WCF | -| `apache_dubbo` | Apache Dubbo | -| `connect_rpc` | Connect RPC | - +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -To avoid high cardinality, implementations should prefer the most stable of `server.address` or -`server.socket.address`, depending on expected deployment profile. For many cloud applications, this is likely -`server.address` as names can be recycled even across re-instantiation of a server with a different `ip`. +| Value | Description | Stability | +|---|---|---| +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + For client-side metrics `server.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to). For server-side spans `server.port` is optional (it describes the port the client is connecting from). @@ -146,4 +288,9 @@ More specific Semantic Conventions are defined for the following RPC technologie * [gRPC](grpc.md): Semantic Conventions for *gRPC*. * [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +Specifications defined by maintainers of RPC systems: + +* [gRPC](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md): Semantic Conventions for *gRPC*. + +[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/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index c86dfc3cac..b03bb96910 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -14,13 +14,12 @@ This document defines how to describe remote procedure calls - [Common remote procedure call conventions](#common-remote-procedure-call-conventions) - * [Span name](#span-name) - * [Common attributes](#common-attributes) - + [Service name](#service-name) - * [Client attributes](#client-attributes) - * [Server attributes](#server-attributes) - * [Events](#events) - * [Distinction from HTTP spans](#distinction-from-http-spans) + - [Span name](#span-name) + - [Service name](#service-name) + - [Client attributes](#client-attributes) + - [Server attributes](#server-attributes) + - [Events](#events) + - [Distinction from HTTP spans](#distinction-from-http-spans) - [Semantic Conventions for specific RPC technologies](#semantic-conventions-for-specific-rpc-technologies) @@ -30,25 +29,26 @@ This document defines how to describe remote procedure calls > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/rpc.md) > (or prior): > -> * SHOULD NOT change the version of the networking attributes that they emit +> * SHOULD NOT change the version of the networking conventions that they emit > until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in RPC instrumentations). +> include stabilization of a core set of networking conventions which are also used +> in RPC instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable networking attributes, -> and stop emitting the old experimental networking attributes +> * `http` - emit the new, stable networking conventions, +> and stop emitting the old experimental networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable networking attributes, +> * `http/dup` - emit both the old and the stable networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental networking attributes +> emitting whatever version of the old experimental networking conventions > the instrumentation was emitting previously. +> * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). +> for at least six months after it starts emitting both sets of conventions. +> * SHOULD drop the environment variable in the next major version. ## Common remote procedure call conventions @@ -78,89 +78,144 @@ Examples of span names: `MyServiceReference.ICalculator/Add` reported by the client for .NET WCF calls - `MyServiceWithNoPackage/theMethod` -### Common attributes +### Service name - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | -| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended | -| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended | -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/attributes.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | -| [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: See below | -| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | See below | -| [`server.socket.port`](../general/attributes.md) | int | Physical server port. | `16456` | Recommended: [4] | +On the server process receiving and handling the remote procedure call, the service name provided in `rpc.service` does not necessarily have to match the [`service.name`][] resource attribute. +One process can expose multiple RPC endpoints and thus have multiple RPC service names. From a deployment perspective, as expressed by the `service.*` resource attributes, it will be treated as one deployed service with one `service.name`. +Likewise, on clients sending RPC requests to a server, the service name provided in `rpc.service` does not have to match the [`peer.service`][] span attribute. -**[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). +As an example, given a process deployed as `QuoteService`, this would be the name that goes into the `service.name` resource attribute which applies to the entire process. +This process could expose two RPC endpoints, one called `CurrencyQuotes` (= `rpc.service`) with a method called `getMeanRate` (= `rpc.method`) and the other endpoint called `StockQuotes` (= `rpc.service`) with two methods `getCurrentBid` and `getLastClose` (= `rpc.method`). +In this example, spans representing client request should have their `peer.service` attribute set to `QuoteService` as well to match the server's `service.name` resource attribute. +Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service name. -**[2]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). +[`service.name`]: /docs/resource/README.md#service +[`peer.service`]: /docs/general/attributes.md#general-remote-service-attributes -**[3]:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. +### Client attributes -**[4]:** If different than `server.port` and if `server.socket.address` is set. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.system`](/docs/attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc`; `java_rmi`; `dotnet_wcf` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | `Conditionally Required` [3] | ![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. | `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 `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [4] | `tcp`; `udp` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.type`](/docs/attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [5] | `ipv4`; `ipv6` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [6] | `exampleMethod` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [7] | `myservice.EchoService` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**Additional attribute requirements:** At least one of the following sets of attributes is required: +**[1]:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. -* [`server.socket.address`](../general/attributes.md) -* [`server.address`](../general/attributes.md) +**[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. -`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +**[3]:** if the port is supported by the network transport used for communication. -| Value | Description | -|---|---| -| `grpc` | gRPC | -| `java_rmi` | Java RMI | -| `dotnet_wcf` | .NET WCF | -| `apache_dubbo` | Apache Dubbo | -| `connect_rpc` | Connect RPC | - +**[4]:** The value SHOULD be normalized to lowercase. -For client-side spans `server.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to). -For server-side spans `client.socket.port` is optional (it describes the port the client is connecting from). +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. -#### Service name +**[5]:** The value SHOULD be normalized to lowercase. -On the server process receiving and handling the remote procedure call, the service name provided in `rpc.service` does not necessarily have to match the [`service.name`][] resource attribute. -One process can expose multiple RPC endpoints and thus have multiple RPC service names. From a deployment perspective, as expressed by the `service.*` resource attributes, it will be treated as one deployed service with one `service.name`. -Likewise, on clients sending RPC requests to a server, the service name provided in `rpc.service` does not have to match the [`peer.service`][] span attribute. +**[6]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). -As an example, given a process deployed as `QuoteService`, this would be the name that goes into the `service.name` resource attribute which applies to the entire process. -This process could expose two RPC endpoints, one called `CurrencyQuotes` (= `rpc.service`) with a method called `getMeanRate` (= `rpc.method`) and the other endpoint called `StockQuotes` (= `rpc.service`) with two methods `getCurrentBid` and `getLastClose` (= `rpc.method`). -In this example, spans representing client request should have their `peer.service` attribute set to `QuoteService` as well to match the server's `service.name` resource attribute. -Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service name. +**[7]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). -[`service.name`]: /docs/resource/README.md#service -[`peer.service`]: /docs/general/attributes.md#general-remote-service-attributes +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -### Client attributes +| Value | Description | Stability | +|---|---|---| +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`server.socket.domain`](../general/attributes.md) | string | The domain name of an immediate peer. [1] | `proxy.example.com` | Recommended: [2] | +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -**[1]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. +| Value | Description | Stability | +|---|---|---| +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[2]:** If different than `server.address` and if `server.socket.address` is set. +`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ### Server attributes - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`client.address`](../general/attributes.md) | string | Client address - unix domain socket name, IPv4 or IPv6 address. [1] | `/tmp/my.sock`; `10.1.2.80` | Recommended | -| [`client.port`](../general/attributes.md) | int | Client port number [2] | `65123` | Recommended | -| [`client.socket.address`](../general/attributes.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | -| [`client.socket.port`](../general/attributes.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. | -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.system`](/docs/attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc`; `java_rmi`; `dotnet_wcf` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | `Conditionally Required` [3] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`client.address`](/docs/attributes-registry/client.md) | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`client.port`](/docs/attributes-registry/client.md) | int | Client port number. [5] | `65123` | `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. | `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 `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [6] | `tcp`; `udp` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.type`](/docs/attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [7] | `ipv4`; `ipv6` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [8] | `exampleMethod` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [9] | `myservice.EchoService` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + +**[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. + +**[3]:** if the port is supported by the network transport used for communication. + +**[4]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. + +**[5]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. + +**[6]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[7]:** The value SHOULD be normalized to lowercase. + +**[8]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[9]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dotnet_wcf` | .NET WCF | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `apache_dubbo` | Apache Dubbo | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `connect_rpc` | Connect RPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent client address behind any intermediaries (e.g. proxies) if it's available. +`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent client port behind any intermediaries (e.g. proxies) if it's available. +| Value | Description | Stability | +|---|---|---| +| `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ### Events @@ -169,24 +224,24 @@ In the lifetime of an RPC stream, an event for each message sent/received on client and server spans SHOULD be created. In case of unary calls only one sent and one received message will be recorded for both client and server spans. - -The event name MUST be `message`. + +The event name MUST be `rpc.message` -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `message.type` | string | Whether this is a received or sent message. | `SENT` | Recommended | -| `message.id` | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | | Recommended | -| `message.compressed_size` | int | Compressed size of the message in bytes. | | Recommended | -| `message.uncompressed_size` | int | Uncompressed size of the message in bytes. | | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.message.compressed_size`](/docs/attributes-registry/rpc.md) | int | Compressed size of the message in bytes. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.message.id`](/docs/attributes-registry/rpc.md) | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.message.type`](/docs/attributes-registry/rpc.md) | string | Whether this is a received or sent message. | `SENT`; `RECEIVED` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.message.uncompressed_size`](/docs/attributes-registry/rpc.md) | int | Uncompressed size of the message in bytes. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** This way we guarantee that the values will be consistent between different implementations. -`message.type` MUST be one of the following: +`rpc.message.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Value | Description | -|---|---| -| `SENT` | sent | -| `RECEIVED` | received | +| Value | Description | Stability | +|---|---|---| +| `SENT` | sent | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `RECEIVED` | received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ### Distinction from HTTP spans @@ -203,4 +258,4 @@ More specific Semantic Conventions are defined for the following RPC technologie * [gRPC](grpc.md): Semantic Conventions for *gRPC*. * [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/runtime/README.md b/docs/runtime/README.md new file mode 100644 index 0000000000..9a7fcaf3ad --- /dev/null +++ b/docs/runtime/README.md @@ -0,0 +1,57 @@ + + +# Semantic Conventions for Runtime Environment + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions for +runtime environment spans, metrics and logs. + + + + + +- [Metrics](#metrics) + - [Attributes](#attributes) + + + +## Metrics + +Runtime environments vary widely in their terminology, implementation, and +relative values for a given metric. For example, Go and Python are both +garbage collected languages, but comparing heap usage between the Go and +CPython runtimes directly is not meaningful. For this reason, this document +does not propose any standard top-level runtime metric instruments. See [OTEP +108](https://github.com/open-telemetry/oteps/pull/108/files) for additional +discussion. + +Metrics specific to a certain runtime environment should be prefixed with +the runtime's top-level namespace `{environment}.*`, e.g., `jvm.*` and follow the +[general metric semantic convention guidelines](/docs/general/metrics.md#general-metric-semantic-conventions). + +Authors of runtime instrumentations are responsible for the choice of +`{environment}` to avoid ambiguity when interpreting a metric's name or values. + +For example, some programming languages have multiple runtime environments +that vary significantly in their implementation, like [Python which has many +implementations](https://wiki.python.org/moin/PythonImplementations). For +such languages, consider using specific `{environment}` prefixes to avoid +ambiguity, like `cpython.*` and `pypy.*`. + +Also consider the +[general metrics](/docs/general/metrics.md#general-metric-semantic-conventions), +[system metrics](/docs/system/system-metrics.md) and +[OS process metrics](/docs/system/process-metrics.md) +semantic conventions when instrumenting runtime environments. + +- [JVM](jvm-metrics.md) + +### Attributes + +[`process.runtime`](/docs/resource/process.md#process-runtimes) +resource attributes SHOULD be included on runtime metric events as appropriate. + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md new file mode 100644 index 0000000000..c1fbf23158 --- /dev/null +++ b/docs/runtime/jvm-metrics.md @@ -0,0 +1,459 @@ + + +# Semantic Conventions for JVM Metrics + +**Status**: [Mixed][DocumentStatus] + +This document describes semantic conventions for JVM metrics in OpenTelemetry. + + + + + +- [JVM Memory](#jvm-memory) + - [Metric: `jvm.memory.used`](#metric-jvmmemoryused) + - [Metric: `jvm.memory.committed`](#metric-jvmmemorycommitted) + - [Metric: `jvm.memory.limit`](#metric-jvmmemorylimit) + - [Metric: `jvm.memory.used_after_last_gc`](#metric-jvmmemoryused_after_last_gc) +- [JVM Garbage Collection](#jvm-garbage-collection) + - [Metric: `jvm.gc.duration`](#metric-jvmgcduration) +- [JVM Threads](#jvm-threads) + - [Metric: `jvm.thread.count`](#metric-jvmthreadcount) +- [JVM Classes](#jvm-classes) + - [Metric: `jvm.class.loaded`](#metric-jvmclassloaded) + - [Metric: `jvm.class.unloaded`](#metric-jvmclassunloaded) + - [Metric: `jvm.class.count`](#metric-jvmclasscount) +- [JVM CPU](#jvm-cpu) + - [Metric: `jvm.cpu.time`](#metric-jvmcputime) + - [Metric: `jvm.cpu.count`](#metric-jvmcpucount) + - [Metric: `jvm.cpu.recent_utilization`](#metric-jvmcpurecent_utilization) +- [Experimental](#experimental) + - [Metric: `jvm.memory.init`](#metric-jvmmemoryinit) + - [Metric: `jvm.system.cpu.utilization`](#metric-jvmsystemcpuutilization) + - [Metric: `jvm.system.cpu.load_1m`](#metric-jvmsystemcpuload_1m) + - [Metric: `jvm.buffer.memory.usage`](#metric-jvmbuffermemoryusage) + - [Metric: `jvm.buffer.memory.limit`](#metric-jvmbuffermemorylimit) + - [Metric: `jvm.buffer.count`](#metric-jvmbuffercount) + + + +## JVM Memory + +**Status**: [Stable][DocumentStatus] + +**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.memory.*` + +### Metric: `jvm.memory.used` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.memory.used` | UpDownCounter | `By` | Measure of memory used. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`jvm.memory.pool.name`](/docs/attributes-registry/jvm.md) | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`jvm.memory.type`](/docs/attributes-registry/jvm.md) | string | The type of memory. | `heap`; `non_heap` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). + +`jvm.memory.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `heap` | Heap memory. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `non_heap` | Non-heap memory | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +### Metric: `jvm.memory.committed` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.memory.committed` | UpDownCounter | `By` | Measure of memory committed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`jvm.memory.pool.name`](/docs/attributes-registry/jvm.md) | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`jvm.memory.type`](/docs/attributes-registry/jvm.md) | string | The type of memory. | `heap`; `non_heap` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). + +`jvm.memory.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `heap` | Heap memory. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `non_heap` | Non-heap memory | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +### Metric: `jvm.memory.limit` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.memory.limit` | UpDownCounter | `By` | Measure of max obtainable memory. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`jvm.memory.pool.name`](/docs/attributes-registry/jvm.md) | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`jvm.memory.type`](/docs/attributes-registry/jvm.md) | string | The type of memory. | `heap`; `non_heap` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). + +`jvm.memory.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `heap` | Heap memory. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `non_heap` | Non-heap memory | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +### Metric: `jvm.memory.used_after_last_gc` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`MemoryPoolMXBean#getCollectionUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getCollectionUsage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.memory.used_after_last_gc` | UpDownCounter | `By` | Measure of memory used, as measured after the most recent garbage collection event on this pool. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`jvm.memory.pool.name`](/docs/attributes-registry/jvm.md) | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`jvm.memory.type`](/docs/attributes-registry/jvm.md) | string | The type of memory. | `heap`; `non_heap` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). + +`jvm.memory.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `heap` | Heap memory. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `non_heap` | Non-heap memory | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +## JVM Garbage Collection + +**Status**: [Stable][DocumentStatus] + +**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.gc.*` + +### Metric: `jvm.gc.duration` + +This metric is [recommended][MetricRecommended]. +This metric is obtained by subscribing to +[`GarbageCollectionNotificationInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GarbageCollectionNotificationInfo.html) events provided by [`GarbageCollectorMXBean`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/GarbageCollectorMXBean.html). The duration value is obtained from [`GcInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GcInfo.html#getDuration--) + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/metrics/api.md#instrument-advisory-parameters) +of `[ 0.01, 0.1, 1, 10 ]`. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.gc.duration` | Histogram | `s` | Duration of JVM garbage collection actions. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`jvm.gc.action`](/docs/attributes-registry/jvm.md) | string | Name of the garbage collector action. [1] | `end of minor GC`; `end of major GC` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`jvm.gc.name`](/docs/attributes-registry/jvm.md) | string | Name of the garbage collector. [2] | `G1 Young Generation`; `G1 Old Generation` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()). + +**[2]:** Garbage collector name is generally obtained via [GarbageCollectionNotificationInfo#getGcName()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcName()). + + +## JVM Threads + +**Status**: [Stable][DocumentStatus] + +**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.thread.*` + +### Metric: `jvm.thread.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from a combination of + +* [`ThreadMXBean#getAllThreadIds()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getAllThreadIds--) +* [`ThreadMXBean#getThreadInfo()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getThreadInfo-long:A-) +* [`ThreadInfo#getThreadState()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadInfo.html#getThreadState--) +* [`ThreadInfo#isDaemon()`](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/ThreadInfo.html#isDaemon()) (requires Java 9+) + +Note that this is the number of platform threads (as opposed to virtual threads). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.thread.count` | UpDownCounter | `{thread}` | Number of executing platform threads. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`jvm.thread.daemon`](/docs/attributes-registry/jvm.md) | boolean | Whether the thread is daemon or not. | | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`jvm.thread.state`](/docs/attributes-registry/jvm.md) | string | State of the thread. | `runnable`; `blocked` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`jvm.thread.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `new` | A thread that has not yet started is in this state. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `runnable` | A thread executing in the Java virtual machine is in this state. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `blocked` | A thread that is blocked waiting for a monitor lock is in this state. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `waiting` | A thread that is waiting indefinitely for another thread to perform a particular action is in this state. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `timed_waiting` | A thread that is waiting for another thread to perform an action for up to a specified waiting time is in this state. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `terminated` | A thread that has exited is in this state. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +## JVM Classes + +**Status**: [Stable][DocumentStatus] + +**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.class.*` + +### Metric: `jvm.class.loaded` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`ClassLoadingMXBean#getTotalLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getTotalLoadedClassCount--). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.class.loaded` | Counter | `{class}` | Number of classes loaded since JVM start. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + + + +### Metric: `jvm.class.unloaded` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`ClassLoadingMXBean#getUnloadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getUnloadedClassCount--). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.class.unloaded` | Counter | `{class}` | Number of classes unloaded since JVM start. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + + + +### Metric: `jvm.class.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`ClassLoadingMXBean#getLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getLoadedClassCount--). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.class.count` | UpDownCounter | `{class}` | Number of classes currently loaded. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + + + +## JVM CPU + +**Status**: [Stable][DocumentStatus] + +**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.cpu.*` + +### Metric: `jvm.cpu.time` + +This metric is [recommended][MetricRecommended]. + +This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getProcessCpuTime()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuTime()) on HotSpot +and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuTime()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuTime--) on OpenJ9. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.cpu.time` | Counter | `s` | CPU time used by the process as reported by the JVM. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + + + +### Metric: `jvm.cpu.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`Runtime#availableProcessors()`](https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#availableProcessors--). +Note that this is always an integer value (i.e. fractional or millicores are not represented). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.cpu.count` | UpDownCounter | `{cpu}` | Number of processors available to the Java virtual machine. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + + + +### Metric: `jvm.cpu.recent_utilization` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()) on HotSpot +and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuLoad--) on OpenJ9. +Note that the JVM does not provide a definition of what "recent" means. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.cpu.recent_utilization` | Gauge | `1` | Recent CPU utilization for the process as reported by the JVM. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()). + + + + + +## Experimental + +**Status**: [Experimental][DocumentStatus] + +**Description:** Experimental Java Virtual Machine (JVM) metrics captured under `jvm.` + +### Metric: `jvm.memory.init` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.memory.init` | UpDownCounter | `By` | Measure of initial memory requested. | ![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 | +|---|---|---|---|---|---| +| [`jvm.memory.pool.name`](/docs/attributes-registry/jvm.md) | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`jvm.memory.type`](/docs/attributes-registry/jvm.md) | string | The type of memory. | `heap`; `non_heap` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). + +`jvm.memory.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `heap` | Heap memory. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `non_heap` | Non-heap memory | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +### Metric: `jvm.system.cpu.utilization` + +This metric is [Opt-In][MetricOptIn]. +This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getSystemCpuLoad()) on Java version 8..13, [`com.sun.management.OperatingSystemMXBean#getCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()) on Java version 14+, +and [`com.ibm.lang.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html) on OpenJ9. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.system.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the whole system as reported by the JVM. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()). + + + + + +### Metric: `jvm.system.cpu.load_1m` + +This metric is [Opt-In][MetricOptIn]. +This metric is obtained from [`OperatingSystemMXBean#getSystemLoadAverage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.system.cpu.load_1m` | Gauge | `{run_queue_item}` | Average CPU load of the whole system for the last minute as reported by the JVM. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The value range is [0,n], where n is the number of CPU cores - or a negative number if the value is not available. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/java.management/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage()). + + + + + +### Metric: `jvm.buffer.memory.usage` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getMemoryUsed--). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.buffer.memory.usage` | UpDownCounter | `By` | Measure of memory used by buffers. | ![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 | +|---|---|---|---|---|---| +| [`jvm.buffer.pool.name`](/docs/attributes-registry/jvm.md) | string | Name of the buffer pool. [1] | `mapped`; `direct` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). + + +### Metric: `jvm.buffer.memory.limit` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`BufferPoolMXBean#getTotalCapacity()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getTotalCapacity--). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.buffer.memory.limit` | UpDownCounter | `By` | Measure of total memory capacity of buffers. | ![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 | +|---|---|---|---|---|---| +| [`jvm.buffer.pool.name`](/docs/attributes-registry/jvm.md) | string | Name of the buffer pool. [1] | `mapped`; `direct` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). + + +### Metric: `jvm.buffer.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`BufferPoolMXBean#getCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getCount--). + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `jvm.buffer.count` | UpDownCounter | `{buffer}` | Number of buffers in the pool. | ![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 | +|---|---|---|---|---|---| +| [`jvm.buffer.pool.name`](/docs/attributes-registry/jvm.md) | string | Name of the buffer pool. [1] | `mapped`; `direct` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md +[MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/docs/system/README.md b/docs/system/README.md index 7e6be0f0e4..9b83a84a0e 100644 --- a/docs/system/README.md +++ b/docs/system/README.md @@ -1,7 +1,7 @@ @@ -16,6 +16,6 @@ System semantic conventions are defined for the following metrics: * [System](system-metrics.md): For standard system metrics. * [Hardware](hardware-metrics.md): For hardware-related metrics. * [Process](process-metrics.md): For standard process metrics. -* [Runtime Environment](runtime-environment-metrics.md): For runtime environment metrics. +* [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/system/container-metrics.md b/docs/system/container-metrics.md new file mode 100644 index 0000000000..87c3db0087 --- /dev/null +++ b/docs/system/container-metrics.md @@ -0,0 +1,105 @@ + + +# Semantic Conventions for Container Metrics + +**Status**: [Experimental][DocumentStatus] + +## Container Metrics + +### Metric: `container.cpu.time` + +This metric is [opt-in][MetricOptIn]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `container.cpu.time` | Counter | `s` | Total CPU time consumed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Total CPU time consumed by the specific container on all available CPU cores + + + +| 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) | + +`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 | +|---|---|---| +| `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) | +| `system` | When CPU is used by the system (host OS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `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) | + + +### Metric: `container.memory.usage` + +This metric is [opt-in][MetricOptIn]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `container.memory.usage` | Counter | `By` | Memory usage of the container. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Memory usage of the container. + + + + + +### Metric: `container.disk.io` + +This metric is [opt-in][MetricOptIn]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `container.disk.io` | Counter | `By` | Disk bytes for the container. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The total number of bytes read/written successfully (aggregated from all disks). + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`disk.io.direction`](/docs/attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`disk.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `read` | read | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `write` | write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `container.network.io` + +This metric is [opt-in][MetricOptIn]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `container.network.io` | Counter | `By` | Network bytes for the container. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The number of bytes sent/received on all network interfaces by the container. + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`network.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `transmit` | transmit | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `receive` | receive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/metrics/metric-requirement-level.md#opt-in diff --git a/docs/system/hardware-metrics.md b/docs/system/hardware-metrics.md index 7c45d8bdcf..9773606d91 100644 --- a/docs/system/hardware-metrics.md +++ b/docs/system/hardware-metrics.md @@ -14,25 +14,36 @@ when creating instruments not explicitly defined in the specification. - [Common hardware attributes](#common-hardware-attributes) - [Metric Instruments](#metric-instruments) - * [`hw.` - Common hardware metrics](#hw---common-hardware-metrics) - * [`hw.host.` - Physical host metrics](#hwhost---physical-host-metrics) - * [`hw.battery.` - Battery metrics](#hwbattery---battery-metrics) - * [`hw.cpu.` - Physical processor metrics](#hwcpu---physical-processor-metrics) - * [`hw.disk_controller.` - Disk controller metrics](#hwdisk_controller---disk-controller-metrics) - * [`hw.enclosure.` - Enclosure metrics](#hwenclosure---enclosure-metrics) - * [`hw.fan.` - Fan metrics](#hwfan---fan-metrics) - * [`hw.gpu.` - GPU metrics](#hwgpu---gpu-metrics) - * [`hw.logical_disk.`- Logical disk metrics](#hwlogical_disk--logical-disk-metrics) - * [`hw.memory.` - Memory module metrics](#hwmemory---memory-module-metrics) - * [`hw.network.` - Network adapter metrics](#hwnetwork---network-adapter-metrics) - * [`hw.physical_disk.`- Physical disk metrics](#hwphysical_disk--physical-disk-metrics) - * [`hw.power_supply.` - Power supply metrics](#hwpower_supply---power-supply-metrics) - * [`hw.tape_drive.` - Tape drive metrics](#hwtape_drive---tape-drive-metrics) - * [`hw.temperature.` - Temperature sensor metrics](#hwtemperature---temperature-sensor-metrics) - * [`hw.voltage.` - Voltage sensor metrics](#hwvoltage---voltage-sensor-metrics) + - [`hw.` - Common hardware metrics](#hw---common-hardware-metrics) + - [`hw.host.` - Physical host metrics](#hwhost---physical-host-metrics) + - [`hw.battery.` - Battery metrics](#hwbattery---battery-metrics) + - [`hw.cpu.` - Physical processor metrics](#hwcpu---physical-processor-metrics) + - [`hw.disk_controller.` - Disk controller metrics](#hwdisk_controller---disk-controller-metrics) + - [`hw.enclosure.` - Enclosure metrics](#hwenclosure---enclosure-metrics) + - [`hw.fan.` - Fan metrics](#hwfan---fan-metrics) + - [`hw.gpu.` - GPU metrics](#hwgpu---gpu-metrics) + - [`hw.logical_disk.`- Logical disk metrics](#hwlogical_disk--logical-disk-metrics) + - [`hw.memory.` - Memory module metrics](#hwmemory---memory-module-metrics) + - [`hw.network.` - Network adapter metrics](#hwnetwork---network-adapter-metrics) + - [`hw.physical_disk.`- Physical disk metrics](#hwphysical_disk--physical-disk-metrics) + - [`hw.power_supply.` - Power supply metrics](#hwpower_supply---power-supply-metrics) + - [`hw.tape_drive.` - Tape drive metrics](#hwtape_drive---tape-drive-metrics) + - [`hw.temperature.` - Temperature sensor metrics](#hwtemperature---temperature-sensor-metrics) + - [`hw.voltage.` - Voltage sensor metrics](#hwvoltage---voltage-sensor-metrics) +> **Warning** +> Existing instrumentations and collector that are using +> [v1.21.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.21.0/docs/system/hardware-metrics.md) +> (or prior): +> +> * SHOULD NOT adopt any breaking changes from document until the system +> semantic conventions are marked stable. Conventions include, but are not +> limited to, attributes, metric names, and unit of measure. +> * SHOULD introduce a control mechanism to allow users to opt-in to the new +> conventions once the migration plan is finalized. + ## Common hardware attributes All metrics in `hw.` instruments should be attached to a [Host Resource](/docs/resource/host.md) @@ -270,7 +281,7 @@ fiber channel port or a Wi-Fi adapter. | `hw.errors` | Number of errors encountered by the network adapter | {error} | Counter | Int64 | `hw.error.type` (Recommended) | `zero_buffer_credit`, `crc`, etc. | | | | | | | `hw.type` (**Required**) | `network` | | | | | | | `direction` (Recommended) | `receive`, `transmit` | -| `hw.network.bandwidth.limit` | Link speed | By | UpDownCounter | Int64 | | | +| `hw.network.bandwidth.limit` | Link speed | By/s | UpDownCounter | Int64 | | | | `hw.network.bandwidth.utilization` | Utilization of the network bandwidth as a fraction | 1 | Gauge | Double | | | | `hw.network.io` | Received and transmitted network traffic in bytes | By | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` | | `hw.network.packets` | Received and transmitted network traffic in packets (or frames) | {packet} | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` | @@ -388,4 +399,4 @@ Additional **Recommended** attributes: | ----------------- | ---------------------- | ---------- | | `sensor_location` | Location of the sensor | `PS0 V3_3` | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index d287b94a7d..dfb0dc13af 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -13,39 +13,229 @@ instruments not explicitly defined in this document. OS process metrics are not related to the runtime environment of the program, and should take measurements from the operating system. For runtime environment metrics see [semantic conventions for runtime environment -metrics](runtime-environment-metrics.md). +metrics](/docs/runtime/README.md#metrics). -- [Metric Instruments](#metric-instruments) - * [Process](#process) -- [Attributes](#attributes) +- [Process Metrics](#process-metrics) + - [Metric: `process.cpu.time`](#metric-processcputime) + - [Metric: `process.cpu.utilization`](#metric-processcpuutilization) + - [Metric: `process.memory.usage`](#metric-processmemoryusage) + - [Metric: `process.memory.virtual`](#metric-processmemoryvirtual) + - [Metric: `process.disk.io`](#metric-processdiskio) + - [Metric: `process.network.io`](#metric-processnetworkio) + - [Metric: `process.thread.count`](#metric-processthreadcount) + - [Metric: `process.open_file_descriptor.count`](#metric-processopen_file_descriptorcount) + - [Metric: `process.context_switches`](#metric-processcontext_switches) + - [Metric: `process.paging.faults`](#metric-processpagingfaults) -## Metric Instruments +> **Warning** Existing instrumentations and collector that are using +> [v1.21.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.21.0/docs/system/process-metrics.md) +> (or prior): +> +> * SHOULD NOT adopt any breaking changes from document until the system +> semantic conventions are marked stable. Conventions include, but are not +> limited to, attributes, metric names, and unit of measure. +> * SHOULD introduce a control mechanism to allow users to opt-in to the new +> conventions once the migration plan is finalized. -### Process +## Process Metrics -Below is a table of Process metric instruments. +### Metric: `process.cpu.time` -| Name | Instrument Type ([\*](/docs/general/metrics.md#instrument-types)) | Unit | Description | Labels | -|---------------------------------|----------------------------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `process.cpu.time` | Counter | s | Total CPU seconds broken down by different states. | `state`, if specified, SHOULD be one of: `system`, `user`, `wait`. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | -| `process.cpu.utilization` | Gauge | 1 | Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process. | `state`, if specified, SHOULD be one of: `system`, `user`, `wait`. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | -| `process.memory.usage` | UpDownCounter | By | The amount of physical memory in use. | | -| `process.memory.virtual` | UpDownCounter | By | The amount of committed virtual memory. | | -| `process.disk.io` | Counter | By | Disk bytes transferred. | `direction` SHOULD be one of: `read`, `write` | -| `process.network.io` | Counter | By | Network bytes transferred. | `direction` SHOULD be one of: `receive`, `transmit` | -| `process.threads` | UpDownCounter | {thread} | Process threads count. | | -| `process.open_file_descriptors` | UpDownCounter | {count} | Number of file descriptors in use by the process. | | -| `process.context_switches` | Counter | {count} | Number of times the process has been context switched. | `type` SHOULD be one of: `involuntary`, `voluntary` | -| `process.paging.faults` | Counter | {fault} | Number of page faults the process has made. | `type`, if specified, SHOULD be one of: `major` (for major, or hard, page faults), `minor` (for minor, or soft, page faults). | +This metric is [recommended][MetricRecommended]. -## Attributes + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `process.cpu.time` | Counter | `s` | Total CPU seconds broken down by different states. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + -Process metrics SHOULD be associated with a [`process`](/docs/resource/process.md#process) resource whose attributes provide additional context about the process. + +| 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 | The CPU state for this data point. 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) | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +`process.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `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) | + + +### Metric: `process.cpu.utilization` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `process.cpu.utilization` | Gauge | `1` | Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process. | ![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 | +|---|---|---|---|---|---| +| [`process.cpu.state`](/docs/attributes-registry/process.md) | string | The CPU state for this data point. 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) | + +`process.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `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) | + + +### Metric: `process.memory.usage` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `process.memory.usage` | UpDownCounter | `By` | The amount of physical memory in use. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +### Metric: `process.memory.virtual` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `process.memory.virtual` | UpDownCounter | `By` | The amount of committed virtual memory. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +### Metric: `process.disk.io` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `process.disk.io` | Counter | `By` | Disk bytes transferred. | ![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 | +|---|---|---|---|---|---| +| [`disk.io.direction`](/docs/attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`disk.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `read` | read | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `write` | write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `process.network.io` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `process.network.io` | Counter | `By` | Network bytes transferred. | ![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 | +|---|---|---|---|---|---| +| [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`network.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `transmit` | transmit | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `receive` | receive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `process.thread.count` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `process.thread.count` | UpDownCounter | `{thread}` | Process threads count. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +### Metric: `process.open_file_descriptor.count` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `process.open_file_descriptor.count` | UpDownCounter | `{count}` | Number of file descriptors in use by the process. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +### Metric: `process.context_switches` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `process.context_switches` | Counter | `{count}` | Number of times the process has been context switched. | ![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 | +|---|---|---|---|---|---| +| [`process.context_switch_type`](/docs/attributes-registry/process.md) | string | Specifies whether the context switches for this data point were voluntary or involuntary. | `voluntary`; `involuntary` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`process.context_switch_type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `voluntary` | voluntary | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `involuntary` | involuntary | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `process.paging.faults` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `process.paging.faults` | Counter | `{fault}` | Number of page faults the process has made. | ![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 | +|---|---|---|---|---|---| +| [`process.paging.fault_type`](/docs/attributes-registry/process.md) | string | The type of page fault for this data point. Type `major` is for major/hard page faults, and `minor` is for minor/soft page faults. | `major`; `minor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`process.paging.fault_type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `major` | major | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `minor` | minor | ![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/runtime-environment-metrics.md b/docs/system/runtime-environment-metrics.md deleted file mode 100644 index 280450102c..0000000000 --- a/docs/system/runtime-environment-metrics.md +++ /dev/null @@ -1,433 +0,0 @@ - - -# Semantic Conventions for Runtime Environment Metrics - -**Status**: [Experimental][DocumentStatus] - -This document includes semantic conventions for runtime environment level -metrics in OpenTelemetry. Also consider the [general -metric](/docs/general/metrics.md#general-metric-semantic-conventions), [system -metrics](system-metrics.md) and [OS Process metrics](process-metrics.md) -semantic conventions when instrumenting runtime environments. - - - - - -- [Metric Instruments](#metric-instruments) - * [Runtime Environment Specific Metrics - `process.runtime.{environment}.`](#runtime-environment-specific-metrics---processruntimeenvironment) -- [Attributes](#attributes) -- [JVM Metrics](#jvm-metrics) - * [Metric: `process.runtime.jvm.memory.usage`](#metric-processruntimejvmmemoryusage) - * [Metric: `process.runtime.jvm.memory.committed`](#metric-processruntimejvmmemorycommitted) - * [Metric: `process.runtime.jvm.memory.limit`](#metric-processruntimejvmmemorylimit) - * [Metric: `process.runtime.jvm.memory.usage_after_last_gc`](#metric-processruntimejvmmemoryusage_after_last_gc) - * [Metric: `process.runtime.jvm.gc.duration`](#metric-processruntimejvmgcduration) - * [Metric: `process.runtime.jvm.threads.count`](#metric-processruntimejvmthreadscount) - * [Metric: `process.runtime.jvm.classes.loaded`](#metric-processruntimejvmclassesloaded) - * [Metric: `process.runtime.jvm.classes.unloaded`](#metric-processruntimejvmclassesunloaded) - * [Metric: `process.runtime.jvm.classes.current_loaded`](#metric-processruntimejvmclassescurrent_loaded) - * [Metric: `process.runtime.jvm.cpu.time`](#metric-processruntimejvmcputime) - * [Metric: `process.runtime.jvm.cpu.recent_utilization`](#metric-processruntimejvmcpurecent_utilization) -- [JVM Metrics (Experimental)](#jvm-metrics-experimental) - * [Metric: `process.runtime.jvm.memory.init`](#metric-processruntimejvmmemoryinit) - * [Metric: `process.runtime.jvm.system.cpu.utilization`](#metric-processruntimejvmsystemcpuutilization) - * [Metric: `process.runtime.jvm.system.cpu.load_1m`](#metric-processruntimejvmsystemcpuload_1m) - * [Metric: `process.runtime.jvm.buffer.usage`](#metric-processruntimejvmbufferusage) - * [Metric: `process.runtime.jvm.buffer.limit`](#metric-processruntimejvmbufferlimit) - * [Metric: `process.runtime.jvm.buffer.count`](#metric-processruntimejvmbuffercount) - - - -## Metric Instruments - -Runtime environments vary widely in their terminology, implementation, and -relative values for a given metric. For example, Go and Python are both -garbage collected languages, but comparing heap usage between the Go and -CPython runtimes directly is not meaningful. For this reason, this document -does not propose any standard top-level runtime metric instruments. See [OTEP -108](https://github.com/open-telemetry/oteps/pull/108/files) for additional -discussion. - -### Runtime Environment Specific Metrics - `process.runtime.{environment}.` - -Metrics specific to a certain runtime environment should be prefixed with -`process.runtime.{environment}.` and follow the semantic conventions outlined in -[general metric semantic -conventions](/docs/general/metrics.md#general-metric-semantic-conventions). Authors of -runtime instrumentations are responsible for the choice of `{environment}` to -avoid ambiguity when interpreting a metric's name or values. - -For example, some programming languages have multiple runtime environments -that vary significantly in their implementation, like [Python which has many -implementations](https://wiki.python.org/moin/PythonImplementations). For -such languages, consider using specific `{environment}` prefixes to avoid -ambiguity, like `process.runtime.cpython.` and `process.runtime.pypy.`. - -There are other dimensions even within a given runtime environment to -consider, for example pthreads vs green thread implementations. - -## Attributes - -[`process.runtime`](/docs/resource/process.md#process-runtimes) resource attributes SHOULD be included on runtime metric events as appropriate. - -## JVM Metrics - -**Description:** Java Virtual Machine (JVM) metrics captured under `process.runtime.jvm.` - -### Metric: `process.runtime.jvm.memory.usage` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.memory.usage` | UpDownCounter | `By` | Measure of memory used. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `pool` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `process.runtime.jvm.memory.committed` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.memory.committed` | UpDownCounter | `By` | Measure of memory committed. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `pool` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `process.runtime.jvm.memory.limit` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.memory.limit` | UpDownCounter | `By` | Measure of max obtainable memory. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `pool` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `process.runtime.jvm.memory.usage_after_last_gc` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`MemoryPoolMXBean#getCollectionUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getCollectionUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.memory.usage_after_last_gc` | UpDownCounter | `By` | Measure of memory used, as measured after the most recent garbage collection event on this pool. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `pool` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `process.runtime.jvm.gc.duration` - -This metric is [recommended][MetricRecommended]. -This metric is obtained by subscribing to -[`GarbageCollectionNotificationInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GarbageCollectionNotificationInfo.html) events provided by [`GarbageCollectorMXBean`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/GarbageCollectorMXBean.html). The duration value is obtained from [`GcInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GcInfo.html#getDuration--) - -This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/api.md#instrument-advice) -of `[]` (single bucket histogram capturing count, sum, min, max). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.gc.duration` | Histogram | `s` | Duration of JVM garbage collection actions. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `gc` | string | Name of the garbage collector. [1] | `G1 Young Generation`; `G1 Old Generation` | Recommended | -| `action` | string | Name of the garbage collector action. [2] | `end of minor GC`; `end of major GC` | Recommended | - -**[1]:** Garbage collector name is generally obtained via [GarbageCollectionNotificationInfo#getGcName()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcName()). - -**[2]:** Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()). - - -### Metric: `process.runtime.jvm.threads.count` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`ThreadMXBean#getDaemonThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getDaemonThreadCount--) and -[`ThreadMXBean#getThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getThreadCount--). -Note that this is the number of platform threads (as opposed to virtual threads). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.threads.count` | UpDownCounter | `{thread}` | Number of executing platform threads. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `daemon` | boolean | Whether the thread is daemon or not. | | Recommended | - - -### Metric: `process.runtime.jvm.classes.loaded` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`ClassLoadingMXBean#getTotalLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getTotalLoadedClassCount--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.classes.loaded` | Counter | `{class}` | Number of classes loaded since JVM start. | - - - - - -### Metric: `process.runtime.jvm.classes.unloaded` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`ClassLoadingMXBean#getUnloadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getUnloadedClassCount--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.classes.unloaded` | Counter | `{class}` | Number of classes unloaded since JVM start. | - - - - - -### Metric: `process.runtime.jvm.classes.current_loaded` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`ClassLoadingMXBean#getLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getLoadedClassCount--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.classes.current_loaded` | UpDownCounter | `{class}` | Number of classes currently loaded. | - - - - - -### Metric: `process.runtime.jvm.cpu.time` - -This metric is [recommended][MetricRecommended]. - -This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getProcessCpuTime()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuTime()) on HotSpot -and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuTime()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuTime--) on J9. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.cpu.time` | Counter | `s` | CPU time used by the process as reported by the JVM. | - - - - - -### Metric: `process.runtime.jvm.cpu.recent_utilization` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()) on HotSpot -and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuLoad--) on J9. -Note that the JVM does not provide a definition of what "recent" means. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.cpu.recent_utilization` | Gauge | `1` | Recent CPU utilization for the process as reported by the JVM. [1] | - -**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()). - - - - - -## JVM Metrics (Experimental) - -**Description:** Experimental Java Virtual Machine (JVM) metrics captured under `process.runtime.jvm.` - -### Metric: `process.runtime.jvm.memory.init` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.memory.init` | UpDownCounter | `By` | Measure of initial memory requested. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `pool` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `process.runtime.jvm.system.cpu.utilization` - -This metric is [Opt-In][MetricOptIn]. -This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getSystemCpuLoad()) on Java version 8..13, [`com.sun.management.OperatingSystemMXBean#getCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()) on Java version 14+, -and [`com.ibm.lang.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html) on J9. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.system.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the whole system as reported by the JVM. [1] | - -**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()). - - - - - -### Metric: `process.runtime.jvm.system.cpu.load_1m` - -This metric is [Opt-In][MetricOptIn]. -This metric is obtained from [`OperatingSystemMXBean#getSystemLoadAverage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.system.cpu.load_1m` | Gauge | `{run_queue_item}` | Average CPU load of the whole system for the last minute as reported by the JVM. [1] | - -**[1]:** The value range is [0,n], where n is the number of CPU cores - or a negative number if the value is not available. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/java.management/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage()). - - - - - -### Metric: `process.runtime.jvm.buffer.usage` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getMemoryUsed--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.buffer.usage` | UpDownCounter | `By` | Measure of memory used by buffers. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `pool` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | - -**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). - - -### Metric: `process.runtime.jvm.buffer.limit` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`BufferPoolMXBean#getTotalCapacity()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getTotalCapacity--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.buffer.limit` | UpDownCounter | `By` | Measure of total memory capacity of buffers. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `pool` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | - -**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). - - -### Metric: `process.runtime.jvm.buffer.count` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`BufferPoolMXBean#getCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getCount--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.buffer.count` | UpDownCounter | `{buffer}` | Number of buffers in the pool. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `pool` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | - -**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). - - -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md -[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md#opt-in -[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md#recommended diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 3882a55788..822035f264 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -11,156 +11,779 @@ metrics in OpenTelemetry. Consider the [general metric semantic conventions](/docs/general/metrics.md#general-metric-semantic-conventions) when creating instruments not explicitly defined in the specification. +The `system.*` namespace SHOULD be exclusively used to report hosts' metrics. +The `system.*` namespace SHOULD only be used when the metrics are collected from within the target system. (physical servers, virtual machines etc). +Metrics collected from technology-specific, well-defined APIs (e.g. Kubelet's API or container runtimes) +should be reported under their respective namespace (e.g. k8s.*, container.*). +Resource attributes related to a host, SHOULD be reported under the `host.*` namespace. + -- [Metric Instruments](#metric-instruments) - * [`system.cpu.` - Processor metrics](#systemcpu---processor-metrics) - * [`system.memory.` - Memory metrics](#systemmemory---memory-metrics) - * [`system.paging.` - Paging/swap metrics](#systempaging---pagingswap-metrics) - * [`system.disk.` - Disk controller metrics](#systemdisk---disk-controller-metrics) - * [`system.filesystem.` - Filesystem metrics](#systemfilesystem---filesystem-metrics) - * [`system.network.` - Network metrics](#systemnetwork---network-metrics) - * [`system.processes.` - Aggregate system process metrics](#systemprocesses---aggregate-system-process-metrics) - * [`system.{os}.` - OS Specific System Metrics](#systemos---os-specific-system-metrics) +- [Processor Metrics](#processor-metrics) + - [Metric: `system.cpu.time`](#metric-systemcputime) + - [Metric: `system.cpu.utilization`](#metric-systemcpuutilization) + - [Metric: `system.cpu.physical.count`](#metric-systemcpuphysicalcount) + - [Metric: `system.cpu.logical.count`](#metric-systemcpulogicalcount) + - [Metric: `system.cpu.frequency`](#metric-systemcpufrequency) +- [Memory Metrics](#memory-metrics) + - [Metric: `system.memory.usage`](#metric-systemmemoryusage) + - [Metric: `system.memory.limit`](#metric-systemmemorylimit) + - [Metric: `system.memory.shared`](#metric-systemmemoryshared) + - [Metric: `system.memory.utilization`](#metric-systemmemoryutilization) +- [Paging/Swap Metrics](#pagingswap-metrics) + - [Metric: `system.paging.usage`](#metric-systempagingusage) + - [Metric: `system.paging.utilization`](#metric-systempagingutilization) + - [Metric: `system.paging.faults`](#metric-systempagingfaults) + - [Metric: `system.paging.operations`](#metric-systempagingoperations) +- [Disk Controller Metrics](#disk-controller-metrics) + - [Metric: `system.disk.io`](#metric-systemdiskio) + - [Metric: `system.disk.operations`](#metric-systemdiskoperations) + - [Metric: `system.disk.io_time`](#metric-systemdiskio_time) + - [Metric: `system.disk.operation_time`](#metric-systemdiskoperation_time) + - [Metric: `system.disk.merged`](#metric-systemdiskmerged) +- [Filesystem Metrics](#filesystem-metrics) + - [Metric: `system.filesystem.usage`](#metric-systemfilesystemusage) + - [Metric: `system.filesystem.utilization`](#metric-systemfilesystemutilization) +- [Network Metrics](#network-metrics) + - [Metric: `system.network.dropped`](#metric-systemnetworkdropped) + - [Metric: `system.network.packets`](#metric-systemnetworkpackets) + - [Metric: `system.network.errors`](#metric-systemnetworkerrors) + - [Metric: `system.network.io`](#metric-systemnetworkio) + - [Metric: `system.network.connections`](#metric-systemnetworkconnections) +- [Aggregate System Process Metrics](#aggregate-system-process-metrics) + - [Metric: `system.process.count`](#metric-systemprocesscount) + - [Metric: `system.process.created`](#metric-systemprocesscreated) +- [`system.{os}.` - OS Specific System Metrics](#systemos---os-specific-system-metrics) + - [Metric: `system.linux.memory.available`](#metric-systemlinuxmemoryavailable) -## Metric Instruments - -### `system.cpu.` - Processor metrics - -**Description:** System level processor metrics. - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | -| ---------------------- | -------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ---------------- | ----------------------------------- | -| system.cpu.time | | s | Counter | Double | state | idle, user, system, interrupt, etc. | -| | | | | | cpu | CPU number [0..n-1] | -| system.cpu.utilization | Difference in system.cpu.time since the last measurement, divided by the elapsed time and number of CPUs | 1 | Gauge | Double | state | idle, user, system, interrupt, etc. | -| | | | | | cpu | CPU number (0..n) | - -### `system.memory.` - Memory metrics - -**Description:** System level memory metrics. This does not include [paging/swap -memory](#systempaging---pagingswap-metrics). - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ------------------------- | ----------- | ----- | ------------------------------------------------- | ---------- | ------------- | ------------------------ | -| system.memory.usage | | By | UpDownCounter | Int64 | state | used, free, cached, etc. | -| system.memory.utilization | | 1 | Gauge | Double | state | used, free, cached, etc. | - -### `system.paging.` - Paging/swap metrics - -**Description:** System level paging/swap memory metrics. - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -|---------------------------|-------------------------------------|--------------|---------------------------------------------------|------------|---------------|------------------| -| system.paging.usage | Unix swap or windows pagefile usage | By | UpDownCounter | Int64 | state | used, free | -| system.paging.utilization | | 1 | Gauge | Double | state | used, free | -| system.paging.faults | | {fault} | Counter | Int64 | type | major, minor | -| system.paging.operations | | {operation} | Counter | Int64 | type | major, minor | -| | | | | | direction | in, out | - -### `system.disk.` - Disk controller metrics - -**Description:** System level disk performance metrics. - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -|--------------------------------------------|-------------------------------------------------|--------------|---------------------------------------------------|------------|---------------|------------------| -| system.disk.io | | By | Counter | Int64 | device | (identifier) | -| | | | | | direction | read, write | -| system.disk.operations | | {operation} | Counter | Int64 | device | (identifier) | -| | | | | | direction | read, write | -| system.disk.io_time\[1\] | Time disk spent activated | s | Counter | Double | device | (identifier) | -| system.disk.operation_time\[2\] | Sum of the time each operation took to complete | s | Counter | Double | device | (identifier) | -| | | | | | direction | read, write | -| system.disk.merged | | {operation} | Counter | Int64 | device | (identifier) | -| | | | | | direction | read, write | - -1 The real elapsed time ("wall clock") -used in the I/O path (time from operations running in parallel are not -counted). Measured as: - -- Linux: Field 13 from -[procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) -- Windows: The complement of ["Disk\% Idle -Time"](https://docs.microsoft.com/en-us/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained:~:text=%25%20Idle%20Time,Idle\)%20to%200%20(meaning%20always%20busy).) -performance counter: `uptime * (100 - "Disk\% Idle Time") / 100` - -2 Because it is the sum of time each -request took, parallel-issued requests each contribute to make the count -grow. Measured as: - -- Linux: Fields 7 & 11 from -[procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) -- Windows: "Avg. Disk sec/Read" perf counter multiplied by "Disk Reads/sec" -perf counter (similar for Writes) - -### `system.filesystem.` - Filesystem metrics - -**Description:** System level filesystem metrics. - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ----------------------------- | ----------- | ----- | ------------------------------------------------- | ---------- | ------------- | -------------------- | -| system.filesystem.usage | | By | UpDownCounter | Int64 | device | (identifier) | -| | | | | | state | used, free, reserved | -| | | | | | type | ext4, tmpfs, etc. | -| | | | | | mode | rw, ro, etc. | -| | | | | | mountpoint | (path) | -| system.filesystem.utilization | | 1 | Gauge | Double | device | (identifier) | -| | | | | | state | used, free, reserved | -| | | | | | type | ext4, tmpfs, etc. | -| | | | | | mode | rw, ro, etc. | -| | | | | | mountpoint | (path) | - -### `system.network.` - Network metrics - -**Description:** System level network metrics. - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -|----------------------------------------|-------------------------------------------------------------------------------|---------------|---------------------------------------------------|------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| system.network.dropped\[1\] | Count of packets that are dropped or discarded even though there was no error | {packet} | Counter | Int64 | device | (identifier) | -| | | | | | direction | transmit, receive | -| system.network.packets | | {packet} | Counter | Int64 | device | (identifier) | -| | | | | | direction | transmit, receive | -| system.network.errors\[2\] | Count of network errors detected | {error} | Counter | Int64 | device | (identifier) | -| | | | | | direction | transmit, receive | -| system.network.io | | By | Counter | Int64 | device | (identifier) | -| | | | | | direction | transmit, receive | -| system.network.connections | | {connection} | UpDownCounter | Int64 | device | (identifier) | -| | | | | | protocol | tcp, udp, [etc.](https://en.wikipedia.org/wiki/Transport_layer#Protocols) | -| | | | | | state | If specified, SHOULD be one of: close, close_wait, closing, delete, established, fin_wait_1, fin_wait_2, last_ack, listen, syn_recv, syn_sent, time_wait. A stateless protocol MUST NOT set this attribute. | - -1 Measured as: - -- Linux: the `drop` column in `/proc/dev/net` -([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)). -- Windows: -[`InDiscards`/`OutDiscards`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) -from -[`GetIfEntry2`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/nf-netioapi-getifentry2). - -2 Measured as: - -- Linux: the `errs` column in `/proc/dev/net` -([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)). -- Windows: -[`InErrors`/`OutErrors`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) -from -[`GetIfEntry2`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/nf-netioapi-getifentry2). - -### `system.processes.` - Aggregate system process metrics - -**Description:** System level aggregate process metrics. For metrics at the -individual process level, see [process metrics](process-metrics.md). - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ------------------------ | --------------------------------------------------------- | ----------- | ------------------------------------------------- | ---------- | ------------- | ---------------------------------------------------------------------------------------------- | -| system.processes.count | Total number of processes in each state | {process} | UpDownCounter | Int64 | status | running, sleeping, [etc.](https://man7.org/linux/man-pages/man1/ps.1.html#PROCESS_STATE_CODES) | -| system.processes.created | Total number of processes created over uptime of the host | {process} | Counter | Int64 | - | - | - -### `system.{os}.` - OS Specific System Metrics +> **Warning** Existing instrumentations and collector that are using +> [v1.21.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.21.0/docs/system/system-metrics.md) +> (or prior): +> +> * SHOULD NOT adopt any breaking changes from document until the system +> semantic conventions are marked stable. Conventions include, but are not +> limited to, attributes, metric names, and unit of measure. +> * SHOULD introduce a control mechanism to allow users to opt-in to the new +> conventions once the migration plan is finalized. + +## Processor Metrics + +**Description:** System level processor metrics captured under the namespace `system.cpu`. + +### Metric: `system.cpu.time` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.cpu.time` | Counter | `s` | Seconds each logical CPU spent on each mode | ![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 | +|---|---|---|---|---|---| +| [`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. + +| Value | Description | Stability | +|---|---|---| +| `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `system.cpu.utilization` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.cpu.utilization` | Gauge | `1` | Difference in system.cpu.time since the last measurement, divided by the elapsed time and number of logical CPUs | ![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 | +|---|---|---|---|---|---| +| [`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. + +| Value | Description | Stability | +|---|---|---| +| `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `system.cpu.physical.count` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.cpu.physical.count` | UpDownCounter | `{cpu}` | Reports the number of actual physical processor cores on the hardware | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +### Metric: `system.cpu.logical.count` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.cpu.logical.count` | UpDownCounter | `{cpu}` | Reports the number of logical (virtual) processor cores created by the operating system to manage multitasking | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +### Metric: `system.cpu.frequency` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.cpu.frequency` | Gauge | `{Hz}` | Reports the current frequency of the CPU in Hz | ![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 | +|---|---|---|---|---|---| +| [`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) | + + +## Memory Metrics + +**Description:** System level memory metrics capture under the namespace `system.memory`. +This does not include [paging/swap memory](#pagingswap-metrics). + +### Metric: `system.memory.usage` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.memory.usage` | UpDownCounter | `By` | Reports memory in use by state. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The sum over all `system.memory.state` values SHOULD equal the total memory +available on the system, that is `system.memory.limit`. + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`system.memory.state`](/docs/attributes-registry/system.md) | string | The memory state | `free`; `cached` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.memory.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `used` | used | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `free` | free | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `shared` | shared | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed, report shared memory usage with `metric.system.memory.shared` metric | +| `buffers` | buffers | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cached` | cached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `system.memory.limit` + +This metric is [opt-in][MetricOptIn]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.memory.limit` | UpDownCounter | `By` | Total memory available in the system. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Its value SHOULD equal the sum of `system.memory.state` over all states. + + + + + +### Metric: `system.memory.shared` + +This metric is [opt-in][MetricOptIn]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.memory.shared` | UpDownCounter | `By` | Shared memory used (mostly by tmpfs). [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Equivalent of `shared` from [`free` command](https://man7.org/linux/man-pages/man1/free.1.html) or +`Shmem` from [`/proc/meminfo`](https://man7.org/linux/man-pages/man5/proc.5.html)" + + + + + +### Metric: `system.memory.utilization` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.memory.utilization` | Gauge | `1` | | ![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 | +|---|---|---|---|---|---| +| [`system.memory.state`](/docs/attributes-registry/system.md) | string | The memory state | `free`; `cached` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.memory.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `used` | used | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `free` | free | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `shared` | shared | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed, report shared memory usage with `metric.system.memory.shared` metric | +| `buffers` | buffers | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cached` | cached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +## Paging/Swap Metrics + +**Description:** System level paging/swap memory metrics captured under the namespace `system.paging`. + +### Metric: `system.paging.usage` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.paging.usage` | UpDownCounter | `By` | Unix swap or windows pagefile usage | ![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 | +|---|---|---|---|---|---| +| [`system.paging.state`](/docs/attributes-registry/system.md) | string | The memory paging state | `free` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.paging.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `used` | used | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `free` | free | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `system.paging.utilization` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.paging.utilization` | Gauge | `1` | | ![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 | +|---|---|---|---|---|---| +| [`system.paging.state`](/docs/attributes-registry/system.md) | string | The memory paging state | `free` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.paging.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `used` | used | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `free` | free | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `system.paging.faults` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.paging.faults` | Counter | `{fault}` | | ![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 | +|---|---|---|---|---|---| +| [`system.paging.type`](/docs/attributes-registry/system.md) | string | The memory paging type | `minor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.paging.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `major` | major | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `minor` | minor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `system.paging.operations` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.paging.operations` | Counter | `{operation}` | | ![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 | +|---|---|---|---|---|---| +| [`system.paging.direction`](/docs/attributes-registry/system.md) | string | The paging access direction | `in` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.paging.type`](/docs/attributes-registry/system.md) | string | The memory paging type | `minor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.paging.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `in` | in | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `out` | out | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.paging.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `major` | major | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `minor` | minor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +## Disk Controller Metrics + +**Description:** System level disk performance metrics captured under the namespace `system.disk`. + +### Metric: `system.disk.io` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.disk.io` | Counter | `By` | | ![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 | +|---|---|---|---|---|---| +| [`disk.io.direction`](/docs/attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`disk.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `read` | read | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `write` | write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `system.disk.operations` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.disk.operations` | Counter | `{operation}` | | ![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 | +|---|---|---|---|---|---| +| [`disk.io.direction`](/docs/attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`disk.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `read` | read | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `write` | write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `system.disk.io_time` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.disk.io_time` | Counter | `s` | Time disk spent activated [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The real elapsed time ("wall clock") used in the I/O path (time from operations running in parallel are not counted). Measured as: + +- Linux: Field 13 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) +- Windows: The complement of + ["Disk\% Idle Time"](https://learn.microsoft.com/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained) + performance counter: `uptime * (100 - "Disk\% Idle Time") / 100` + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `system.disk.operation_time` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.disk.operation_time` | Counter | `s` | Sum of the time each operation took to complete [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Because it is the sum of time each request took, parallel-issued requests each contribute to make the count grow. Measured as: + +- Linux: Fields 7 & 11 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) +- Windows: "Avg. Disk sec/Read" perf counter multiplied by "Disk Reads/sec" perf counter (similar for Writes) + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`disk.io.direction`](/docs/attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`disk.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `read` | read | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `write` | write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `system.disk.merged` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.disk.merged` | Counter | `{operation}` | | ![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 | +|---|---|---|---|---|---| +| [`disk.io.direction`](/docs/attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`disk.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `read` | read | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `write` | write | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +## Filesystem Metrics + +**Description:** System level filesystem metrics captured under the namespace `system.filesystem`. + +### Metric: `system.filesystem.usage` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.filesystem.usage` | UpDownCounter | `By` | | ![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 | +|---|---|---|---|---|---| +| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.filesystem.mode`](/docs/attributes-registry/system.md) | string | The filesystem mode | `rw, ro` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.filesystem.mountpoint`](/docs/attributes-registry/system.md) | string | The filesystem mount path | `/mnt/data` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.filesystem.state`](/docs/attributes-registry/system.md) | string | The filesystem state | `used` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.filesystem.type`](/docs/attributes-registry/system.md) | string | The filesystem type | `ext4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.filesystem.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `used` | used | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `free` | free | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `reserved` | reserved | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.filesystem.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `fat32` | fat32 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `exfat` | exfat | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ntfs` | ntfs | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `refs` | refs | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hfsplus` | hfsplus | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ext4` | ext4 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `system.filesystem.utilization` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.filesystem.utilization` | Gauge | `1` | | ![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 | +|---|---|---|---|---|---| +| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.filesystem.mode`](/docs/attributes-registry/system.md) | string | The filesystem mode | `rw, ro` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.filesystem.mountpoint`](/docs/attributes-registry/system.md) | string | The filesystem mount path | `/mnt/data` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.filesystem.state`](/docs/attributes-registry/system.md) | string | The filesystem state | `used` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.filesystem.type`](/docs/attributes-registry/system.md) | string | The filesystem type | `ext4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.filesystem.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `used` | used | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `free` | free | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `reserved` | reserved | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.filesystem.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `fat32` | fat32 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `exfat` | exfat | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ntfs` | ntfs | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `refs` | refs | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hfsplus` | hfsplus | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ext4` | ext4 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +## Network Metrics + +**Description:** System level network metrics captured under the namespace `system.network`. + +### Metric: `system.network.dropped` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.network.dropped` | Counter | `{packet}` | Count of packets that are dropped or discarded even though there was no error [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Measured as: + +- Linux: the `drop` column in `/proc/dev/net` ([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)) +- Windows: [`InDiscards`/`OutDiscards`](https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) + from [`GetIfEntry2`](https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2) + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`network.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `transmit` | transmit | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `receive` | receive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `system.network.packets` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.network.packets` | Counter | `{packet}` | | ![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 | +|---|---|---|---|---|---| +| [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`network.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `transmit` | transmit | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `receive` | receive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `system.network.errors` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.network.errors` | Counter | `{error}` | Count of network errors detected [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Measured as: + +- Linux: the `errs` column in `/proc/dev/net` ([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)). +- Windows: [`InErrors`/`OutErrors`](https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) + from [`GetIfEntry2`](https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2). + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`network.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `transmit` | transmit | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `receive` | receive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `system.network.io` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.network.io` | Counter | `By` | | ![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 | +|---|---|---|---|---|---| +| [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`network.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `transmit` | transmit | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `receive` | receive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `system.network.connections` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.network.connections` | UpDownCounter | `{connection}` | | ![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 | +|---|---|---|---|---|---| +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`system.network.state`](/docs/attributes-registry/system.md) | string | A stateless protocol MUST NOT set this attribute | `close_wait` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`system.network.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `close` | close | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `close_wait` | close_wait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `closing` | closing | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `delete` | delete | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `established` | established | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `fin_wait_1` | fin_wait_1 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `fin_wait_2` | fin_wait_2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `last_ack` | last_ack | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `listen` | listen | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `syn_recv` | syn_recv | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `syn_sent` | syn_sent | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `time_wait` | time_wait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Aggregate System Process Metrics + +**Description:** System level aggregate process metrics captured under the namespace `system.process`. +For metrics at the individual process level, see [process metrics](process-metrics.md). + +### Metric: `system.process.count` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.process.count` | UpDownCounter | `{process}` | Total number of processes in each state | ![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 | +|---|---|---|---|---|---| +| [`system.process.status`](/docs/attributes-registry/system.md) | string | The process state, e.g., [Linux Process State Codes](https://man7.org/linux/man-pages/man1/ps.1.html#PROCESS_STATE_CODES) | `running` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.process.status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `running` | running | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `sleeping` | sleeping | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `stopped` | stopped | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `defunct` | defunct | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `system.process.created` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.process.created` | Counter | `{process}` | Total number of processes created over uptime of the host | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +## `system.{os}.` - OS Specific System Metrics Instrument names for system level metrics that have different and conflicting meaning across multiple OSes should be prefixed with `system.{os}.` and @@ -168,7 +791,7 @@ follow the hierarchies listed above for different entities like CPU, memory, and network. For example, [UNIX load -average](https://en.wikipedia.org/wiki/Load_(computing)) over a given +average](https://wikipedia.org/wiki/Load_(computing)) over a given interval is not well standardized and its value across different UNIX like OSes may vary despite being under similar load: @@ -188,4 +811,20 @@ An instrument for load average over 1 minute on Linux could be named `system.linux.cpu.load_1m`, reusing the `cpu` name proposed above and having an `{os}` prefix to split this metric across OSes. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended +[MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in + +### Metric: `system.linux.memory.available` + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.linux.memory.available` | UpDownCounter | `By` | An estimate of how much memory is available for starting new applications, without causing swapping [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This is an alternative to `system.memory.usage` metric with `state=free`. +Linux starting from 3.14 exports "available" memory. It takes "free" memory as a baseline, and then factors in kernel-specific values. +This is supposed to be more accurate than just "free" memory. +For reference, see the calculations [here](https://superuser.com/a/980821). +See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html). + diff --git a/docs/url/README.md b/docs/url/README.md index af111395de..7618e189ae 100644 --- a/docs/url/README.md +++ b/docs/url/README.md @@ -1,7 +1,7 @@ @@ -15,4 +15,4 @@ URL semantic conventions are defined for the following: * [URL](url.md): For describing URL and its components. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/docs/url/url.md b/docs/url/url.md index 0661c8dd8f..8cf2ce6fec 100644 --- a/docs/url/url.md +++ b/docs/url/url.md @@ -23,21 +23,21 @@ This document defines semantic conventions that describe URL and its components. ## Attributes -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Recommended | -| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | -| `url.path` | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [2] | `/search` | Recommended | -| `url.query` | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [3] | `q=OpenTelemetry` | Recommended | -| `url.fragment` | string | The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component | `SemConv` | Recommended | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`url.fragment`](/docs/attributes-registry/url.md) | string | The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component | `SemConv` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.full`](/docs/attributes-registry/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.path`](/docs/attributes-registry/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [2] | `/search` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.query`](/docs/attributes-registry/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [3] | `q=OpenTelemetry` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. -`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`. -`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes. +**[1]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. +`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. -**[2]:** When missing, the value is assumed to be `/` +**[2]:** Sensitive content provided in `url.path` SHOULD be scrubbed when instrumentations can identify it. -**[3]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. +**[3]:** Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it. ## Sensitive information @@ -48,4 +48,4 @@ Instrumentations that are aware of specific sensitive query string parameters MU _Note: Applications and telemetry consumers should scrub sensitive information from URL attributes on collected telemetry. In systems unable to identify sensitive information, certain attribute values may be redacted entirely._ -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/gulpfile.js b/gulpfile.js index a42fd496e5..b01927ecc0 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -4,8 +4,8 @@ const markdownlint = require("markdownlint"); const yaml = require("js-yaml"); const fs = require("fs"); -let fileCount = 0, - issueCount = 0; +let numFilesProcessed = 0, + numFilesWithIssues = 0; function markdownLintFile(file, encoding, callback) { const config = yaml.load(fs.readFileSync("./.markdownlint.yaml", "utf8")); @@ -33,9 +33,11 @@ function markdownLintFile(file, encoding, callback) { .join("\n"); if (resultString) { console.log(resultString); - issueCount++; + numFilesWithIssues++; + // Don't report an error yet so that other files can be checked: + // callback(new Error('...')); } - fileCount++; + numFilesProcessed++; callback(null, file); }); } @@ -47,11 +49,13 @@ function lintMarkdown() { .src(markdownFiles) .pipe(through2.obj(markdownLintFile)) .on("end", () => { - console.log( - `Processed ${fileCount} file${ - fileCount == 1 ? "" : "s" - }, ${issueCount} had issues.`, - ); + const fileOrFiles = "file" + (numFilesProcessed == 1 ? "" : "s"); + const msg = `Processed ${numFilesProcessed} ${fileOrFiles}, ${numFilesWithIssues} had issues.`; + if (numFilesWithIssues > 0) { + throw new Error(msg); + } else { + console.log(msg); + } }); } diff --git a/internal/tools/go.mod b/internal/tools/go.mod index aeac23a1d3..d0b9f54cf0 100644 --- a/internal/tools/go.mod +++ b/internal/tools/go.mod @@ -2,4 +2,7 @@ module github.com/open-telemetry/opentelemetry-specification/internal/tools go 1.12 -require github.com/client9/misspell v0.3.4 +require ( + github.com/client9/misspell v0.3.4 + go.opentelemetry.io/build-tools/chloggen v0.12.0 +) diff --git a/internal/tools/go.sum b/internal/tools/go.sum index ee5948021f..67e22ae48f 100644 --- a/internal/tools/go.sum +++ b/internal/tools/go.sum @@ -1,2 +1,29 @@ github.com/client9/misspell v0.3.4 h1:ta993UF76GwbvJcIo3Y68y/M3WxlpEHPWIGDkJYwzJI= github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw= +github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= +github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= +github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= +github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= +github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= +github.com/spf13/cobra v1.7.0 h1:hyqWnYt1ZQShIddO5kBpj3vu05/++x6tJ6dg8EC572I= +github.com/spf13/cobra v1.7.0/go.mod h1:uLxZILRyS/50WlhOIKD7W6V5bgeIt+4sICxh6uRMrb0= +github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA= +github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= +github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= +github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw= +github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo= +github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= +github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU= +github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk= +github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo= +go.opentelemetry.io/build-tools/chloggen v0.12.0 h1:BFj/1bNIGxOs1GykGjhV4gycz1nqVWI/xVDUaVfNibw= +go.opentelemetry.io/build-tools/chloggen v0.12.0/go.mod h1:zuYbAo3TkrHo3C7lCrM5dHWSS50BDr0UfRYtyBFv2dQ= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= +gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= +gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/internal/tools/schema_check.sh b/internal/tools/schema_check.sh index 50c8d5e724..e71451ef7c 100755 --- a/internal/tools/schema_check.sh +++ b/internal/tools/schema_check.sh @@ -6,20 +6,38 @@ set -e -BUILD_TOOL_SCHEMAS_VERSION=0.18.0 +BUILD_TOOL_SCHEMAS_VERSION=0.24.0 # List of versions that do not require or have a schema. declare -a skip_versions=("1.0.0" "1.0.1" "1.1.0" "1.2.0" "1.3.0" "1.6.0") -root_dir=$PWD -schemas_dir=$root_dir/schemas - -# Find all version sections in CHANGELOG that start with a number in 1..9 range. -grep -o -e '## v[1-9].*\s' $root_dir/CHANGELOG.md | grep -o '[1-9].*' | while read ver; do - if [[ " ${skip_versions[*]} " == *" $ver "* ]]; then - # Skip this version, it does not need a schema file. - continue +# Verifies remote avilability of a schema file. +# +# If the schema file is available for download, THEN we make sure it is exactly +# what is in the repository. If the file is not available for download, +# we pass this check. This is to allow releases to be checked in, where +# a new version is specified but hasn't propagated to the website yet. +# +# Args: +# 1 - version number +verify_remote_availability() { + local ver="$1" + echo -n "Ensure published schema file https://opentelemetry.io/schemas/$ver matches local copy... " + if curl --fail --no-progress-meter https://opentelemetry.io/schemas/$ver > verify$ver 2>/dev/null; then + diff verify$ver $file && echo "OK, matches" \ + || (echo "Incorrect!" && exit 3) + else + echo "Not found" fi + rm verify$ver +} + +# Verifies remote avilability of a schema file in the current repository. +# +# Args: +# 1 - version number +verify_local_availability() { + local ver="$1" file="$schemas_dir/$ver" echo -n "Ensure schema file $file exists... " @@ -31,16 +49,20 @@ grep -o -e '## v[1-9].*\s' $root_dir/CHANGELOG.md | grep -o '[1-9].*' | while re echo "FAILED: $file does not exist. The schema file must exist because the version is declared in CHANGELOG.md." exit 3 fi +} + +root_dir=$PWD +schemas_dir=$root_dir/schemas + +# Find all version sections in CHANGELOG that start with a number in 1..9 range. +grep -o -e '## v[1-9].*\s' $root_dir/CHANGELOG.md | grep -o '[1-9].*' | while read ver; do + if [[ " ${skip_versions[*]} " == *" $ver "* ]]; then + # Skip this version, it does not need a schema file. + continue + fi - # Schema file will no be served directly from this repository when linked - # into opentelemetry.io. We disable this for now and need to move the check - # into the website. - # curl --no-progress-meter https://opentelemetry.io/schemas/$ver > verify$ver - # - # diff verify$ver $file && echo "Published schema at https://opentelemetry.io/schemas/$ver is correct" \ - # || (echo "Published schema at https://opentelemetry.io/schemas/$ver is incorrect!" && exit 3) - # - # rm verify$ver + verify_local_availability "$ver" + verify_remote_availability "$ver" done # Now check the content of all schema files in the ../shemas directory. @@ -50,7 +72,7 @@ for file in $schemas_dir/*; do echo -n "Checking schema file $file for version $ver... " - # Check that the version is defined in the schema file. + # Check that the version is defined in the schema file. if ! grep -q "\s$ver:" $file; then echo "FAILED: $ver version definition is not found in $file" exit 1 diff --git a/internal/tools/scripts/update-issue-template-areas.sh b/internal/tools/scripts/update-issue-template-areas.sh new file mode 100755 index 0000000000..da2f81ebcf --- /dev/null +++ b/internal/tools/scripts/update-issue-template-areas.sh @@ -0,0 +1,43 @@ +#!/usr/bin/env bash +# +# Copyright The OpenTelemetry Authors +# SPDX-License-Identifier: Apache-2.0 +# +# Create labels for all semantic convention areas that are in model/registry. +# Existing labels are not affected. +# +# Note that there is a 50-character limit on labels, so some areas may +# not have a corresponding label. + +set -euo pipefail + +CUR_DIRECTORY=$(dirname "$0") +REPO_DIR="$( cd "$CUR_DIRECTORY/../../../" && pwd )" +GITHUB_DIR="$( cd "$REPO_DIR/.github/" && pwd )" +TEMPLATES_DIR="$( cd "$GITHUB_DIR/ISSUE_TEMPLATE" && pwd )" + +AREAS=$(sh "${GITHUB_DIR}/workflows/scripts/get-registry-areas.sh") + +START_AREA_LIST="# Start semconv area list" +END_AREA_LIST="# End semconv area list" + +replacement=" ${START_AREA_LIST}" + +for AREA in ${AREAS}; do + LABEL_NAME=$(basename "${AREA}" .yaml) + replacement="${replacement}\n - area:${LABEL_NAME}" +done + +echo -e "\nStarting to replace areas in ISSUE_TEMPLATES:" +echo -e "---------------------------------------------\n" + +replacement="${replacement}\n ${END_AREA_LIST}" + +echo -e "The replacement text will be:" +echo -e "---------------------------------------------\n" +echo -e $replacement + +find ${TEMPLATES_DIR} -type f -name '*.yaml' -print0 | xargs -0 sed -i "/$START_AREA_LIST/,/$END_AREA_LIST/c\\$replacement" + +echo -e "\nISSUE_TEMPLATES updated successfully" +echo -e "---------------------------------------------" diff --git a/internal/tools/tools.go b/internal/tools/tools.go index bfa021b18f..2a785effdd 100644 --- a/internal/tools/tools.go +++ b/internal/tools/tools.go @@ -13,6 +13,7 @@ // limitations under the License. // +//go:build tools // +build tools package tools @@ -24,4 +25,5 @@ package tools import ( _ "github.com/client9/misspell/cmd/misspell" + _ "go.opentelemetry.io/build-tools/chloggen" ) diff --git a/internal/tools/update_specification_version.sh b/internal/tools/update_specification_version.sh index 761b9cee65..aef6f5f84e 100755 --- a/internal/tools/update_specification_version.sh +++ b/internal/tools/update_specification_version.sh @@ -6,12 +6,15 @@ # Set this to the version number you want to CHANGE in URLs in the repository. -PREVIOUS_SPECIFICATION_VERSION="v1.21.0" +PREVIOUS_SPECIFICATION_VERSION="v1.26.0" # Set this to the version number you want to KEEP in URLs in the repository. -LATEST_SPECIFICATION_VERSION="v1.22.0" +LATEST_SPECIFICATION_VERSION="v1.31.0" # The specific pattern we look for when replacing URLs SPECIFICATION_URL_PREFIX="https://github.com/open-telemetry/opentelemetry-specification/tree/" SPECIFICATION_BLOB_URL_PREFIX="https://github.com/open-telemetry/opentelemetry-specification/blob/" +# The specific pattern we look for updating the Badge with the spec version +SPECIFICATION_BADGE_PREFIX="https://img.shields.io/badge/OTel_specification_version-" +SPECIFICATION_BADGE_RELEASE_TAG_PREFIX="https://github.com/open-telemetry/opentelemetry-specification/releases/tag/" fix_file() { @@ -19,6 +22,8 @@ fix_file() { sed -i \ -e "s,${SPECIFICATION_URL_PREFIX}${PREVIOUS_SPECIFICATION_VERSION},${SPECIFICATION_URL_PREFIX}${LATEST_SPECIFICATION_VERSION},g" \ -e "s,${SPECIFICATION_BLOB_URL_PREFIX}${PREVIOUS_SPECIFICATION_VERSION},${SPECIFICATION_URL_PREFIX}${LATEST_SPECIFICATION_VERSION},g" \ + -e "s,${SPECIFICATION_BADGE_PREFIX}${PREVIOUS_SPECIFICATION_VERSION},${SPECIFICATION_BADGE_PREFIX}${LATEST_SPECIFICATION_VERSION},g" \ + -e "s,${SPECIFICATION_BADGE_RELEASE_TAG_PREFIX}${PREVIOUS_SPECIFICATION_VERSION},${SPECIFICATION_BADGE_RELEASE_TAG_PREFIX}${LATEST_SPECIFICATION_VERSION},g" \ "$1" } diff --git a/model/README.md b/model/README.md index a6c52ba625..dd1886f0ed 100644 --- a/model/README.md +++ b/model/README.md @@ -10,16 +10,16 @@ the generated markdown output in the [docs](../docs/README.md) folder. ## Writing semantic conventions Semantic conventions for the spec MUST adhere to the -[attribute naming](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/common/attribute-naming.md), -[attribute requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/common/attribute-requirement-level.md), -and [metric requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md) conventions. +[attribute naming](../docs/general/attribute-naming.md), +[attribute requirement level](../docs/general/attribute-requirement-level.md), +and [metric requirement level](../docs/general/metric-requirement-level.md) conventions. -Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.18.0/semantic-conventions/syntax.md) +Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.24.0/semantic-conventions/syntax.md) for how to write the YAML files for semantic conventions and what the YAML properties mean. A schema file for VS code is configured in the `/.vscode/settings.json` of this repository, enabling auto-completion and additional checks. Refer to -[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.18.0/semantic-conventions/README.md) for what extension you need. +[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.24.0/semantic-conventions/README.md) for what extension you need. ## Generating markdown @@ -30,7 +30,7 @@ formatted Markdown tables for all semantic conventions in the specification. Run make table-generation ``` -For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.18.0/semantic-conventions) +For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.24.0/semantic-conventions) in the OpenTelemetry build tools repository. Using this build tool, it is also possible to generate code for use in OpenTelemetry language projects. diff --git a/model/db-common.yaml b/model/db-common.yaml new file mode 100644 index 0000000000..7cb8a90c18 --- /dev/null +++ b/model/db-common.yaml @@ -0,0 +1,45 @@ +groups: + - id: attributes.db.client + type: attribute_group + brief: 'Database Client attributes' + attributes: + - ref: db.namespace + requirement_level: + conditionally_required: If available. + - ref: db.collection.name + requirement_level: + conditionally_required: > + If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture + `db.collection.name`, then it SHOULD be the first collection name found in the query. + - ref: db.operation.name + requirement_level: + conditionally_required: > + If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture + `db.operation.name`, then it SHOULD be the first operation name found in the query. + - ref: db.system + requirement_level: required + - ref: network.peer.address + brief: Peer address of the database node where the operation was performed. + requirement_level: + recommended: If applicable for this database system. + note: > + 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. + - ref: network.peer.port + requirement_level: + recommended: if and only if `network.peer.address` is set. + - ref: server.address + brief: > + Name of the database host. + - ref: server.port + requirement_level: + conditionally_required: If using a port other than the default port for this DBMS and if `server.address` is set. + - ref: error.type + requirement_level: + conditionally_required: If and only if the operation failed. + note: > + The `error.type` SHOULD match the error code returned by the database 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. diff --git a/model/deprecated/http.yaml b/model/deprecated/http.yaml deleted file mode 100644 index f904126c67..0000000000 --- a/model/deprecated/http.yaml +++ /dev/null @@ -1,41 +0,0 @@ -groups: - - id: attributes.http.deprecated - type: attribute_group - brief: "Describes deprecated HTTP attributes." - prefix: http - attributes: - - id: method - type: string - brief: 'Deprecated, use `http.request.method` instead.' - stability: deprecated - examples: ["GET", "POST", "HEAD"] - - id: status_code - type: int - brief: 'Deprecated, use `http.response.status_code` instead.' - stability: deprecated - examples: [200] - - id: scheme - type: string - brief: 'Deprecated, use `url.scheme` instead.' - stability: deprecated - examples: ['http', 'https'] - - id: url - type: string - brief: 'Deprecated, use `url.full` instead.' - stability: deprecated - examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv'] - - id: target - type: string - brief: 'Deprecated, use `url.path` and `url.query` instead.' - stability: deprecated - examples: ['/search?q=OpenTelemetry#SemConv'] - - id: request_content_length - type: int - brief: 'Deprecated, use `http.request.body.size` instead.' - stability: deprecated - examples: 3495 - - id: response_content_length - type: int - brief: 'Deprecated, use `http.response.body.size` instead.' - stability: deprecated - examples: 3495 diff --git a/model/destination.yaml b/model/destination.yaml deleted file mode 100644 index 2df72bd9f3..0000000000 --- a/model/destination.yaml +++ /dev/null @@ -1,24 +0,0 @@ -groups: - - id: destination - prefix: destination - type: attribute_group - brief: These attributes may be used to describe the receiver of a network exchange/packet. These should be used - when there is no client/server relationship between the two sides, or when that relationship is unknown. - This covers low-level network interactions (e.g. packet tracing) where you don't know if - there was a connection or which side initiated it. - This also covers unidirectional UDP flows and peer-to-peer communication where the - "user-facing" surface of the protocol / API does not expose a clear notion of client and server. - attributes: - - id: domain - type: string - brief: The domain name of the destination system. - examples: ['foo.example.com'] - note: This value may be a host name, a fully qualified domain name, or another host naming format. - - id: address - type: string - brief: 'Peer address, for example IP address or UNIX socket name.' - examples: ['10.5.3.2'] - - id: port - type: int - brief: 'Peer port number' - examples: [3389, 2888] diff --git a/model/exception.yaml b/model/exception.yaml deleted file mode 100644 index 9f47fb6700..0000000000 --- a/model/exception.yaml +++ /dev/null @@ -1,33 +0,0 @@ -groups: - - id: exception - type: span - prefix: exception - brief: > - This document defines the shared attributes used to - report a single exception associated with a span or log. - attributes: - - id: type - type: string - brief: > - The type of the exception (its fully-qualified class name, if applicable). - The dynamic type of the exception should be preferred over the static type - in languages that support it. - examples: ["java.net.ConnectException", "OSError"] - - id: message - type: string - brief: The exception message. - examples: ["Division by zero", "Can't convert 'int' object to str implicitly"] - - id: stacktrace - type: string - brief: > - A stacktrace as a string in the natural representation for the language runtime. - The representation is to be determined and documented by each language SIG. - examples: 'Exception in thread "main" java.lang.RuntimeException: Test exception\n - at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n - at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n - at com.example.GenerateTrace.main(GenerateTrace.java:5)' - - constraints: - - any_of: - - "exception.type" - - "exception.message" diff --git a/model/faas-common.yaml b/model/faas-common.yaml new file mode 100644 index 0000000000..9d951485b2 --- /dev/null +++ b/model/faas-common.yaml @@ -0,0 +1,21 @@ +groups: + - id: attributes.faas.common + type: attribute_group + brief: "Describes FaaS attributes." + prefix: faas + attributes: + - ref: faas.trigger + - ref: faas.invoked_name + requirement_level: required + - ref: faas.invoked_provider + requirement_level: required + - ref: faas.invoked_region + requirement_level: + conditionally_required: > + For some cloud providers, like AWS or GCP, the region in which a + function is hosted is essential to uniquely identify the function + and also part of its endpoint. Since it's part of the endpoint + being called, the region is always known to clients. In these cases, + `faas.invoked_region` MUST be set accordingly. If the region is + unknown to the client or not required for identifying the invoked + function, setting `faas.invoked_region` is optional. diff --git a/model/general.yaml b/model/general.yaml new file mode 100644 index 0000000000..26df3efc1a --- /dev/null +++ b/model/general.yaml @@ -0,0 +1,66 @@ +groups: + - id: client + type: attribute_group + brief: > + General client attributes. + attributes: + - ref: client.address + - ref: client.port + - id: server + type: attribute_group + brief: > + General server attributes. + attributes: + - ref: server.address + - ref: server.port + - id: source + type: attribute_group + brief: > + General source attributes. + attributes: + - ref: source.address + - ref: source.port + - id: destination + type: attribute_group + brief: > + General destination attributes. + attributes: + - ref: destination.address + - ref: destination.port + - id: peer + prefix: peer + type: span + brief: "Operations that access some remote service." + attributes: + - ref: peer.service + requirement_level: recommended + - id: identity + type: span + brief: > + These attributes may be used for any operation with an authenticated and/or authorized enduser. + attributes: + - ref: enduser.id + requirement_level: recommended + - ref: enduser.role + requirement_level: recommended + - ref: enduser.scope + requirement_level: recommended + - id: thread + type: span + brief: > + These attributes may be used for any operation to store information about a thread that started a span. + attributes: + - ref: thread.id + - ref: thread.name + - id: code + type: span + brief: > + These attributes allow to report this unit of code and therefore to provide more context about the span. + attributes: + - ref: code.function + - ref: code.namespace + - ref: code.filepath + - ref: code.lineno + - ref: code.column + - ref: code.stacktrace + requirement_level: opt_in diff --git a/model/http-common.yaml b/model/http-common.yaml index 682b2cb984..2187943dda 100644 --- a/model/http-common.yaml +++ b/model/http-common.yaml @@ -2,140 +2,86 @@ groups: - id: attributes.http.common type: attribute_group brief: "Describes HTTP attributes." - prefix: http attributes: - - id: request.method - type: - allow_custom_values: true - members: - - id: connect - value: "CONNECT" - brief: 'CONNECT method.' - - id: delete - value: "DELETE" - brief: 'DELETE method.' - - id: get - value: "GET" - brief: 'GET method.' - - id: head - value: "HEAD" - brief: 'HEAD method.' - - id: options - value: "OPTIONS" - brief: 'OPTIONS method.' - - id: patch - value: "PATCH" - brief: 'PATCH method.' - - id: post - value: "POST" - brief: 'POST method.' - - id: put - value: "PUT" - brief: 'PUT method.' - - id: trace - value: "TRACE" - brief: 'TRACE method.' - - id: other - value: "_OTHER" - brief: 'Any HTTP method that the instrumentation has no prior knowledge of.' + - ref: http.request.method requirement_level: required - brief: 'HTTP request method.' - examples: ["GET", "POST", "HEAD"] + - ref: http.response.status_code + requirement_level: + conditionally_required: If and only if one was received/sent. + - ref: error.type + requirement_level: + conditionally_required: If request has ended with an error. + examples: ['timeout', 'java.net.UnknownHostException', 'server_certificate_invalid', '500'] note: | - HTTP request method value SHOULD be "known" to the instrumentation. - By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) - and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). + If the request fails with an error before response status code was sent or received, + `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) + or a component-specific low cardinality error identifier. - If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER` and, except if reporting a metric, MUST - set the exact method received in the request line as value of the `http.request.method_original` attribute. + If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), + `error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. - If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override - the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named - OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods - (this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). + The `error.type` value SHOULD be predictable and SHOULD have low cardinality. + Instrumentations SHOULD document the list of errors they report. - HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. - Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. - Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. - - id: response.status_code - type: int - requirement_level: - conditionally_required: If and only if one was received/sent. - brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).' - examples: [200] + The cardinality of `error.type` within one instrumentation library SHOULD be low, but + 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 request has completed successfully, instrumentations SHOULD NOT set `error.type`. - ref: network.protocol.name examples: ['http', 'spdy'] requirement_level: - recommended: if not default (`http`). + conditionally_required: If not `http` and `network.protocol.version` is set. - ref: network.protocol.version - examples: ['1.0', '1.1', '2.0'] + examples: ['1.0', '1.1', '2', '3'] - id: attributes.http.client - prefix: http type: attribute_group brief: 'HTTP Client attributes' + extends: attributes.http.common attributes: - ref: server.address requirement_level: required brief: > Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: | - Determined by using the first of the following that applies - - - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form - - Host identifier of the `Host` header - - SHOULD NOT be set if capturing it would require an extra DNS lookup. + note: > + If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then + `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. - ref: server.port - requirement_level: - conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). + requirement_level: required brief: > Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: > - When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match - URI port identifier, otherwise it MUST match `Host` header port identifier. + - ref: url.scheme + requirement_level: opt_in + examples: ["http", "https"] - id: attributes.http.server - prefix: http type: attribute_group brief: 'HTTP Server attributes' + extends: attributes.http.common attributes: - - id: route - type: string + - ref: http.route requirement_level: conditionally_required: If and only if it's available - brief: > - The matched route (path template in the format used by the respective server framework). See note below - examples: ['/users/:userID?', '{controller}/{action}/{id?}'] - note: > - MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. - - SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. - ref: server.address brief: > Name of the local HTTP server that received the request. - note: | - Determined by using the first of the following that applies - - - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only - include host identifier. - - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. - - Host identifier of the `Host` header - - SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. - + note: > + See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). - ref: server.port brief: > Port of the local HTTP server that received the request. - note: | - Determined by using the first of the following that applies - - - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. - - Port identifier of the `Host` header + note: > + See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). + requirement_level: + conditionally_required: If `server.address` is set. - ref: url.scheme requirement_level: required examples: ["http", "https"] + note: > + The scheme of the original client request, if known + (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), + [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), + or a similar header). + Otherwise, the scheme of the immediate peer request. diff --git a/model/logs/events.yaml b/model/logs/events.yaml index f3398c9ac1..b07e25a8df 100644 --- a/model/logs/events.yaml +++ b/model/logs/events.yaml @@ -1,32 +1,8 @@ groups: - id: event type: attribute_group - prefix: event brief: > This document defines attributes for Events represented using Log Records. attributes: - - id: name - type: string + - ref: event.name requirement_level: required - brief: > - The name identifies the event. - examples: ['click', 'exception'] - - id: domain - brief: > - The domain identifies the business context for the events. - type: - allow_custom_values: true - members: - - id: browser - value: 'browser' - brief: 'Events from browser apps' - - id: device - value: 'device' - brief: 'Events from mobile apps' - - id: k8s - value: 'k8s' - brief: 'Events from Kubernetes' - requirement_level: required - note: | - Events across different domains may have same `event.name`, yet be - unrelated events. diff --git a/model/logs/general.yaml b/model/logs/general.yaml index 48da970c13..b4afe2c16c 100644 --- a/model/logs/general.yaml +++ b/model/logs/general.yaml @@ -1,19 +1,8 @@ groups: - id: log.record - prefix: log.record type: attribute_group brief: > The attributes described in this section are rather generic. They may be used in any Log Record they apply to. attributes: - - id: uid - type: string + - ref: log.record.uid requirement_level: opt_in - brief: > - A unique identifier for the Log Record. - note: > - If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. - This means, that two distinguishable log records MUST have different values. - - The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), - but other identifiers (e.g. UUID) may be used as needed. - examples: ["01ARZ3NDEKTSV4RRFFQ69G5FAV"] diff --git a/model/logs/log-exception.yaml b/model/logs/log-exception.yaml index d0b251552a..ab20cb7250 100644 --- a/model/logs/log-exception.yaml +++ b/model/logs/log-exception.yaml @@ -7,10 +7,9 @@ groups: Records. attributes: - ref: exception.type + requirement_level: + conditionally_required: Required if `exception.message` is not set, recommended otherwise. - ref: exception.message + requirement_level: + conditionally_required: Required if `exception.type` is not set, recommended otherwise. - ref: exception.stacktrace - - constraints: - - any_of: - - "exception.type" - - "exception.message" diff --git a/model/logs/log-feature_flag.yaml b/model/logs/log-feature_flag.yaml index 6d902423f5..4530096de7 100644 --- a/model/logs/log-feature_flag.yaml +++ b/model/logs/log-feature_flag.yaml @@ -1,7 +1,7 @@ groups: - id: log-feature_flag type: event - prefix: feature_flag + name: feature_flag brief: > This document defines attributes for feature flag evaluations represented using Log Records. diff --git a/model/logs/media.yaml b/model/logs/media.yaml index b8d1c29975..34c7631d5c 100644 --- a/model/logs/media.yaml +++ b/model/logs/media.yaml @@ -1,49 +1,21 @@ groups: - id: attributes.log - prefix: log type: attribute_group brief: "Describes Log attributes" attributes: - - id: iostream + - ref: log.iostream requirement_level: opt_in - brief: > - The stream associated with the log. See below for a list of well-known values. - type: - allow_custom_values: false - members: - - id: stdout - value: 'stdout' - brief: 'Logs from stdout stream' - - id: stderr - value: 'stderr' - brief: 'Events from stderr stream' + - id: attributes.log.file - prefix: log.file type: attribute_group brief: > A file to which log was emitted. attributes: - - id: name - type: string + - ref: log.file.name requirement_level: recommended - brief: > - The basename of the file. - examples: ["audit.log"] - - id: path - type: string + - ref: log.file.path requirement_level: opt_in - brief: > - The full path to the file. - examples: [ "/var/log/mysql/audit.log" ] - - id: name_resolved - type: string + - ref: log.file.name_resolved requirement_level: opt_in - brief: > - The basename of the file, with symlinks resolved. - examples: [ "uuid.log" ] - - id: path_resolved - type: string + - ref: log.file.path_resolved requirement_level: opt_in - brief: > - The full path to the file, with symlinks resolved. - examples: [ "/var/lib/docker/uuid.log" ] diff --git a/model/logs/mobile-events.yaml b/model/logs/mobile-events.yaml new file mode 100644 index 0000000000..4b1d956b21 --- /dev/null +++ b/model/logs/mobile-events.yaml @@ -0,0 +1,76 @@ +groups: + - id: device.app.lifecycle + stability: experimental + type: event + name: device.app.lifecycle + brief: > + This event represents an occurrence of a lifecycle transition on Android or iOS platform. + note: > + This event identifies the fields that are common to all lifecycle events for android and iOS using + the `android.state` and `ios.state` fields. The `android.state` and `ios.state` attributes are + mutually exclusive. + # Future Note: When the build tools support this definition please uncomment and validate the details + # included here and what has been added to the manual markdown table + # body: + # fields: + # - id: ios.state + # stability: experimental + # requirement_level: + # conditional_required: if and only if `os.name` is `ios` + # note: > + # The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), + # and from which the `OS terminology` column values are derived. + # brief: > + # This attribute represents the state the application has transitioned into at the occurrence of the event. + # type: + # allow_custom_values: false + # members: + # - id: active + # value: 'active' + # brief: > + # The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. + # - id: inactive + # value: 'inactive' + # brief: > + # The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. + # - id: background + # value: 'background' + # brief: > + # The app is now in the background. + # This value is associated with UIKit notification `applicationDidEnterBackground`. + # - id: foreground + # value: 'foreground' + # brief: > + # The app is now in the foreground. + # This value is associated with UIKit notification `applicationWillEnterForeground`. + # - id: terminate + # value: 'terminate' + # brief: > + # The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. + # - id: android.state + # stability: experimental + # requirement_level: + # conditional_required: if and only if `os.name` is `android` + # brief: > + # This attribute represents the state the application has transitioned into at the occurrence of the event. + # note: > + # The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), + # and from which the `OS identifiers` are derived. + # type: + # allow_custom_values: false + # members: + # - id: created + # value: 'created' + # brief: > + # Any time before Activity.onResume() or, if the app has no Activity, Context.startService() + # has been called in the app for the first time. + # - id: background + # value: 'background' + # brief: > + # Any time after Activity.onPause() or, if the app has no Activity, + # Context.stopService() has been called when the app was in the foreground state. + # - id: foreground + # value: 'foreground' + # brief: > + # Any time after Activity.onResume() or, if the app has no Activity, + # Context.startService() has been called when the app was in either the created or background states. diff --git a/model/messaging-common.yaml b/model/messaging-common.yaml new file mode 100644 index 0000000000..4728e516fa --- /dev/null +++ b/model/messaging-common.yaml @@ -0,0 +1,19 @@ +groups: + - id: messaging.attributes.common + type: attribute_group + brief: "Common messaging attributes." + prefix: messaging + attributes: + - ref: messaging.system + requirement_level: required + - ref: messaging.destination.partition.id + - ref: error.type + examples: ['amqp:decode-error', 'KAFKA_STORAGE_ERROR', 'channel-error'] + requirement_level: + conditionally_required: If and only if the messaging operation has failed. + - ref: server.address + note: > + Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. + requirement_level: + conditionally_required: If available. + - ref: server.port diff --git a/model/metrics/container.yaml b/model/metrics/container.yaml new file mode 100644 index 0000000000..f0e15ed596 --- /dev/null +++ b/model/metrics/container.yaml @@ -0,0 +1,57 @@ +groups: + # container.cpu.* metrics and attribute group + - id: metric.container.cpu.time + type: metric + metric_name: container.cpu.time + stability: experimental + brief: "Total CPU time consumed" + note: > + Total CPU time consumed by the specific container on all available CPU cores + 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." + requirement_level: opt_in + + # container.memory.* metrics and attribute group + - id: metric.container.memory.usage + type: metric + metric_name: container.memory.usage + stability: experimental + brief: "Memory usage of the container." + note: > + Memory usage of the container. + instrument: counter + unit: "By" + + # container.disk.io.* metrics and attribute group + - id: metric.container.disk.io + type: metric + metric_name: container.disk.io + stability: experimental + brief: "Disk bytes for the container." + note: > + The total number of bytes read/written + successfully (aggregated from all disks). + instrument: counter + unit: "By" + attributes: + - ref: disk.io.direction + - ref: system.device + + # container.network.io.* metrics and attribute group + - id: metric.container.network.io + type: metric + metric_name: container.network.io + stability: experimental + brief: "Network bytes for the container." + note: > + The number of bytes sent/received + on all network interfaces + by the container. + instrument: counter + unit: "By" + attributes: + - ref: network.io.direction + - ref: system.device diff --git a/model/metrics/database-metrics.yaml b/model/metrics/database-metrics.yaml new file mode 100644 index 0000000000..95f884f342 --- /dev/null +++ b/model/metrics/database-metrics.yaml @@ -0,0 +1,110 @@ +groups: + - id: metric.db.client.operation.duration + type: metric + metric_name: db.client.operation.duration + brief: "Duration of database client operations." + instrument: histogram + unit: "s" + stability: experimental + extends: attributes.db.client + + - id: metric.db.client.connection.count + type: metric + metric_name: db.client.connection.count + stability: experimental + brief: "The number of connections that are currently in state described by the `state` attribute" + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: db.client.connections.state + requirement_level: required + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connection.idle.max + type: metric + metric_name: db.client.connection.idle.max + stability: experimental + brief: "The maximum number of idle open connections allowed" + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connection.idle.min + type: metric + metric_name: db.client.connection.idle.min + stability: experimental + brief: "The minimum number of idle open connections allowed" + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connection.max + type: metric + metric_name: db.client.connection.max + stability: experimental + brief: "The maximum number of open connections allowed" + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connection.pending_requests + type: metric + metric_name: db.client.connection.pending_requests + stability: experimental + brief: "The number of pending requests for an open connection, cumulative for the entire pool" + instrument: updowncounter + unit: "{request}" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connection.timeouts + type: metric + metric_name: db.client.connection.timeouts + stability: experimental + brief: "The number of connection timeouts that have occurred trying to obtain a connection from the pool" + instrument: counter + unit: "{timeout}" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connection.create_time + type: metric + metric_name: db.client.connection.create_time + stability: experimental + brief: "The time it took to create a new connection" + instrument: histogram + unit: "s" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connection.wait_time + type: metric + metric_name: db.client.connection.wait_time + stability: experimental + brief: "The time it took to obtain an open connection from the pool" + instrument: histogram + unit: "s" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connection.use_time + type: metric + metric_name: db.client.connection.use_time + stability: experimental + brief: "The time between borrowing a connection and returning it to the pool" + instrument: histogram + unit: "s" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required diff --git a/model/metrics/deprecated/database.yaml b/model/metrics/deprecated/database.yaml new file mode 100644 index 0000000000..5e6332294f --- /dev/null +++ b/model/metrics/deprecated/database.yaml @@ -0,0 +1,110 @@ +groups: + - id: metric.db.client.connections.count.deprecated + type: metric + metric_name: db.client.connections.usage + stability: experimental + deprecated: "Replaced by `db.client.connection.count`." + brief: "Deprecated, use `db.client.connection.count` instead." + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: db.client.connections.state + requirement_level: required + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connections.idle.max.deprecated + type: metric + metric_name: db.client.connections.idle.max + stability: experimental + deprecated: "Replaced by `db.client.connection.idle.max`." + brief: "Deprecated, use `db.client.connection.idle.max` instead." + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connections.idle.min.deprecated + type: metric + metric_name: db.client.connections.idle.min + stability: experimental + deprecated: "Replaced by `db.client.connection.idle.min`." + brief: "Deprecated, use `db.client.connection.idle.min` instead." + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connections.max.deprecated + type: metric + metric_name: db.client.connections.max + stability: experimental + deprecated: "Replaced by `db.client.connection.max`." + brief: "Deprecated, use `db.client.connection.max` instead." + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connections.pending_requests.deprecated + type: metric + metric_name: db.client.connections.pending_requests + stability: experimental + deprecated: "Replaced by `db.client.connection.pending_requests`." + brief: "Deprecated, use `db.client.connection.pending_requests` instead." + instrument: updowncounter + unit: "{request}" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connections.timeouts.deprecated + type: metric + metric_name: db.client.connections.timeouts + stability: experimental + deprecated: "Replaced by `db.client.connection.timeouts`." + brief: "Deprecated, use `db.client.connection.timeouts` instead." + instrument: counter + unit: "{timeout}" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connections.create_time.deprecated + type: metric + metric_name: db.client.connections.create_time + stability: experimental + deprecated: "Replaced by `db.client.connection.create_time`. Note: the unit also changed from `ms` to `s`." + brief: "Deprecated, use `db.client.connection.create_time` instead. Note: the unit also changed from `ms` to `s`." + instrument: histogram + unit: "ms" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connections.wait_time.deprecated + type: metric + metric_name: db.client.connections.wait_time + stability: experimental + deprecated: "Replaced by `db.client.connection.wait_time`. Note: the unit also changed from `ms` to `s`." + brief: "Deprecated, use `db.client.connection.wait_time` instead. Note: the unit also changed from `ms` to `s`." + instrument: histogram + unit: "ms" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connections.use_time.deprecated + type: metric + metric_name: db.client.connections.use_time + stability: experimental + deprecated: "Replaced by `db.client.connection.use_time`. Note: the unit also changed from `ms` to `s`." + brief: "Deprecated, use `db.client.connection.use_time` instead. Note: the unit also changed from `ms` to `s`." + instrument: histogram + unit: "ms" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required diff --git a/model/metrics/dns.yaml b/model/metrics/dns.yaml new file mode 100644 index 0000000000..627213d90f --- /dev/null +++ b/model/metrics/dns.yaml @@ -0,0 +1,23 @@ +groups: + - id: metric.dns.lookup.duration + type: metric + metric_name: dns.lookup.duration + stability: experimental + brief: Measures the time taken to perform a DNS lookup. + instrument: histogram + unit: "s" + attributes: + - ref: dns.question.name + requirement_level: required + examples: ["www.example.com", "dot.net"] + - ref: error.type + requirement_level: + conditionally_required: if and only if an error has occurred. + brief: Describes the error the DNS lookup failed with. + note: > + Instrumentations SHOULD use error code such as one of errors reported by + `getaddrinfo`([Linux or other POSIX systems](https://man7.org/linux/man-pages/man3/getaddrinfo.3.html) / + [Windows](https://learn.microsoft.com/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo)) or one reported by the + runtime or client library. + If error code is not available, the full name of exception type SHOULD be used. + examples: ["host_not_found", "no_recovery", "java.net.UnknownHostException"] diff --git a/model/metrics/dotnet/dotnet-aspnetcore.yaml b/model/metrics/dotnet/dotnet-aspnetcore.yaml new file mode 100644 index 0000000000..fd0c2c4d78 --- /dev/null +++ b/model/metrics/dotnet/dotnet-aspnetcore.yaml @@ -0,0 +1,114 @@ +groups: + - id: aspnetcore.common.rate_limiting.metrics.attributes + type: attribute_group + brief: Common ASP.NET Core rate-limiting metrics attributes + attributes: + - ref: aspnetcore.rate_limiting.policy + requirement_level: + conditionally_required: if the matched endpoint for the request had a rate-limiting policy. + + # routing + - id: metric.aspnetcore.routing.match_attempts + type: metric + metric_name: aspnetcore.routing.match_attempts + stability: stable + brief: Number of requests that were attempted to be matched to an endpoint. + instrument: counter + unit: "{match_attempt}" + note: | + Meter name: `Microsoft.AspNetCore.Routing`; Added in: ASP.NET Core 8.0 + attributes: + - ref: http.route + requirement_level: + conditionally_required: if and only if a route was successfully matched. + - ref: aspnetcore.routing.is_fallback + requirement_level: + conditionally_required: if and only if a route was successfully matched. + - ref: aspnetcore.routing.match_status + requirement_level: required + + # diagnostics + - id: metric.aspnetcore.diagnostics.exceptions + type: metric + metric_name: aspnetcore.diagnostics.exceptions + stability: stable + brief: Number of exceptions caught by exception handling middleware. + instrument: counter + unit: "{exception}" + note: | + Meter name: `Microsoft.AspNetCore.Diagnostics`; Added in: ASP.NET Core 8.0 + attributes: + - ref: error.type + brief: The full name of exception type. + examples: ['System.OperationCanceledException', 'Contoso.MyException'] + requirement_level: required + - ref: aspnetcore.diagnostics.handler.type + - ref: aspnetcore.diagnostics.exception.result + requirement_level: required + + # rate_limiting + - id: metric.aspnetcore.rate_limiting.active_request_leases + type: metric + metric_name: aspnetcore.rate_limiting.active_request_leases + stability: stable + brief: Number of requests that are currently active on the server that hold a rate limiting lease. + instrument: updowncounter + unit: "{request}" + note: | + Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + extends: aspnetcore.common.rate_limiting.metrics.attributes + + - id: metric.aspnetcore.rate_limiting.request_lease.duration + type: metric + metric_name: aspnetcore.rate_limiting.request_lease.duration + stability: stable + brief: The duration of rate limiting lease held by requests on the server. + instrument: histogram + unit: "s" + note: | + Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + extends: aspnetcore.common.rate_limiting.metrics.attributes + + - id: metric.aspnetcore.rate_limiting.request.time_in_queue + type: metric + metric_name: aspnetcore.rate_limiting.request.time_in_queue + stability: stable + brief: The time the request spent in a queue waiting to acquire a rate limiting lease. + instrument: histogram + unit: "s" + note: | + Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + extends: aspnetcore.common.rate_limiting.metrics.attributes + attributes: + - ref: aspnetcore.rate_limiting.result + requirement_level: required + + - id: metric.aspnetcore.rate_limiting.queued_requests + type: metric + metric_name: aspnetcore.rate_limiting.queued_requests + stability: stable + brief: Number of requests that are currently queued, waiting to acquire a rate limiting lease. + instrument: updowncounter + unit: "{request}" + note: | + Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + extends: aspnetcore.common.rate_limiting.metrics.attributes + + - id: metric.aspnetcore.rate_limiting.requests + type: metric + metric_name: aspnetcore.rate_limiting.requests + stability: stable + brief: Number of requests that tried to acquire a rate limiting lease. + instrument: counter + unit: "{request}" + note: | + Requests could be: + + * Rejected by global or endpoint rate limiting policies + * Canceled while waiting for the lease. + + Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + extends: aspnetcore.common.rate_limiting.metrics.attributes + attributes: + - ref: aspnetcore.rate_limiting.result + requirement_level: required diff --git a/model/metrics/dotnet/dotnet-kestrel.yaml b/model/metrics/dotnet/dotnet-kestrel.yaml new file mode 100644 index 0000000000..0d1499a34c --- /dev/null +++ b/model/metrics/dotnet/dotnet-kestrel.yaml @@ -0,0 +1,128 @@ +groups: + - id: common.kestrel.attributes + type: attribute_group + brief: 'Common kestrel attributes' + attributes: + - ref: server.address + - ref: server.port + - ref: network.type + requirement_level: + recommended: if the transport is `tcp` or `udp` + - ref: network.transport + examples: ['tcp', 'unix'] + + - id: metric.kestrel.active_connections + type: metric + metric_name: kestrel.active_connections + stability: stable + brief: Number of connections that are currently active on the server. + instrument: updowncounter + unit: "{connection}" + note: | + Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + extends: common.kestrel.attributes + + - id: metric.kestrel.connection.duration + type: metric + metric_name: kestrel.connection.duration + stability: stable + brief: The duration of connections on the server. + instrument: histogram + unit: "s" + note: | + Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + extends: common.kestrel.attributes + attributes: + - ref: network.protocol.name + examples: ['http', 'web_sockets'] + - ref: network.protocol.version + examples: ["1.1", "2"] + - ref: tls.protocol.version + - ref: error.type + brief: The full name of exception type. + requirement_level: + conditionally_required: if and only if an error has occurred. + note: "Captures the exception type when a connection fails." + examples: ['System.OperationCanceledException', 'Contoso.MyException'] + + - id: metric.kestrel.rejected_connections + type: metric + metric_name: kestrel.rejected_connections + stability: stable + brief: Number of connections rejected by the server. + instrument: counter + unit: "{connection}" + note: | + Connections are rejected when the currently active count exceeds the value configured with `MaxConcurrentConnections`. + Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + extends: common.kestrel.attributes + + - id: metric.kestrel.queued_connections + type: metric + metric_name: kestrel.queued_connections + stability: stable + brief: Number of connections that are currently queued and are waiting to start. + instrument: updowncounter + unit: "{connection}" + note: | + Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + extends: common.kestrel.attributes + + - id: metric.kestrel.queued_requests + type: metric + metric_name: kestrel.queued_requests + stability: stable + brief: Number of HTTP requests on multiplexed connections (HTTP/2 and HTTP/3) that are currently queued and are waiting to start. + instrument: updowncounter + unit: "{request}" + note: | + Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + extends: common.kestrel.attributes + attributes: + - ref: network.protocol.name + examples: ['http', 'web_sockets'] + - ref: network.protocol.version + examples: ["1.1", "2"] + + - id: metric.kestrel.upgraded_connections + type: metric + metric_name: kestrel.upgraded_connections + stability: stable + brief: Number of connections that are currently upgraded (WebSockets). . + instrument: updowncounter + unit: "{connection}" + note: | + The counter only tracks HTTP/1.1 connections. + + Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + extends: common.kestrel.attributes + + - id: metric.kestrel.tls_handshake.duration + type: metric + metric_name: kestrel.tls_handshake.duration + stability: stable + brief: The duration of TLS handshakes on the server. + instrument: histogram + unit: "s" + note: | + Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + extends: common.kestrel.attributes + attributes: + - ref: tls.protocol.version + - ref: error.type + brief: The full name of exception type. + note: "Captures the exception type when a TLS handshake fails." + requirement_level: + conditionally_required: if and only if an error has occurred. + examples: ['System.OperationCanceledException', 'Contoso.MyException'] + + - id: metric.kestrel.active_tls_handshakes + type: metric + metric_name: kestrel.active_tls_handshakes + stability: stable + brief: Number of TLS handshakes that are currently in progress on the server. + instrument: updowncounter + unit: "{handshake}" + note: | + Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + extends: common.kestrel.attributes diff --git a/model/metrics/dotnet/dotnet-signalr.yaml b/model/metrics/dotnet/dotnet-signalr.yaml new file mode 100644 index 0000000000..f91690e925 --- /dev/null +++ b/model/metrics/dotnet/dotnet-signalr.yaml @@ -0,0 +1,26 @@ +groups: + - id: metric.signalr.server.connection.duration + type: metric + metric_name: signalr.server.connection.duration + stability: stable + brief: The duration of connections on the server. + instrument: histogram + unit: "s" + note: | + Meter name: `Microsoft.AspNetCore.Http.Connections`; Added in: ASP.NET Core 8.0 + attributes: + - ref: signalr.connection.status + - ref: signalr.transport + + - id: metric.signalr.server.active_connections + type: metric + metric_name: signalr.server.active_connections + stability: stable + brief: Number of connections that are currently active on the server. + instrument: updowncounter + unit: "{connection}" + note: | + Meter name: `Microsoft.AspNetCore.Http.Connections`; Added in: ASP.NET Core 8.0 + attributes: + - ref: signalr.connection.status + - ref: signalr.transport diff --git a/model/metrics/faas-metrics.yaml b/model/metrics/faas-metrics.yaml new file mode 100644 index 0000000000..238e49df77 --- /dev/null +++ b/model/metrics/faas-metrics.yaml @@ -0,0 +1,90 @@ +groups: + - id: metric.faas.invoke_duration + type: metric + metric_name: faas.invoke_duration + stability: experimental + brief: "Measures the duration of the function's logic execution" + instrument: histogram + unit: "s" + attributes: + - ref: faas.trigger + + - id: metric.faas.init_duration + type: metric + metric_name: faas.init_duration + stability: experimental + brief: "Measures the duration of the function's initialization, such as a cold start" + instrument: histogram + unit: "s" + attributes: + - ref: faas.trigger + + - id: metric.faas.coldstarts + type: metric + metric_name: faas.coldstarts + stability: experimental + brief: "Number of invocation cold starts" + instrument: counter + unit: "{coldstart}" + attributes: + - ref: faas.trigger + + - id: metric.faas.errors + type: metric + metric_name: faas.errors + stability: experimental + brief: "Number of invocation errors" + instrument: counter + unit: "{error}" + attributes: + - ref: faas.trigger + + - id: metric.faas.invocations + type: metric + metric_name: faas.invocations + stability: experimental + brief: "Number of successful invocations" + instrument: counter + unit: "{invocation}" + attributes: + - ref: faas.trigger + + - id: metric.faas.timeouts + type: metric + metric_name: faas.timeouts + stability: experimental + brief: "Number of invocation timeouts" + instrument: counter + unit: "{timeout}" + attributes: + - ref: faas.trigger + + - id: metric.faas.mem_usage + type: metric + metric_name: faas.mem_usage + stability: experimental + brief: "Distribution of max memory usage per invocation" + instrument: histogram + unit: "By" + attributes: + - ref: faas.trigger + + - id: metric.faas.cpu_usage + type: metric + metric_name: faas.cpu_usage + stability: experimental + brief: "Distribution of CPU usage per invocation" + instrument: histogram + unit: "s" + attributes: + - ref: faas.trigger + + - id: metric.faas.net_io + type: metric + metric_name: faas.net_io + stability: experimental + brief: "Distribution of net I/O usage per invocation" + instrument: histogram + unit: "By" + attributes: + - ref: faas.trigger diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml index 385242ddbb..ba1ca5a522 100644 --- a/model/metrics/http.yaml +++ b/model/metrics/http.yaml @@ -5,65 +5,43 @@ groups: extends: attributes.http.server attributes: - ref: server.address - brief: > - Name of the local HTTP server that received the request. requirement_level: opt_in note: | - Determined by using the first of the following that applies - - - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only - include host identifier. - - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. - - Host identifier of the `Host` header - - SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. - + See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). + > **Warning** + > Since this attribute is based on HTTP headers, opting in to it may allow an attacker + > to trigger cardinality limits, degrading the usefulness of the metric. - ref: server.port - brief: > - Port of the local HTTP server that received the request. requirement_level: opt_in note: | - Determined by using the first of the following that applies - - - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. - - Port identifier of the `Host` header - # todo (lmolkova) build tools don't populate grandparent attributes - - ref: http.request.method - - ref: http.response.status_code - - ref: network.protocol.name - - ref: network.protocol.version - + See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). + > **Warning** + > Since this attribute is based on HTTP headers, opting in to it may allow an attacker + > to trigger cardinality limits, degrading the usefulness of the metric. - id: metric_attributes.http.client type: attribute_group brief: 'HTTP client attributes' extends: attributes.http.client - attributes: - # todo (lmolkova) build tools don't populate grandparent attributes - - ref: http.request.method - - ref: http.response.status_code - - ref: network.protocol.name - - ref: network.protocol.version - - ref: server.socket.address - - id: metric.http.server.duration + - id: metric.http.server.request.duration type: metric - metric_name: http.server.duration - brief: "Measures the duration of inbound HTTP requests." + metric_name: http.server.request.duration + brief: "Duration of HTTP server requests." instrument: histogram unit: "s" + stability: stable extends: metric_attributes.http.server - id: metric.http.server.active_requests type: metric metric_name: http.server.active_requests - brief: "Measures the number of concurrent HTTP requests that are currently in-flight." + stability: experimental + brief: "Number of active HTTP server requests." instrument: updowncounter unit: "{request}" attributes: - ref: http.request.method + requirement_level: required - ref: url.scheme requirement_level: required examples: ["http", "https"] @@ -72,64 +50,143 @@ groups: brief: > Name of the local HTTP server that received the request. note: | - Determined by using the first of the following that applies - - - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only - include host identifier. - - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. - - Host identifier of the `Host` header - - SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. - + See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). + > **Warning** + > Since this attribute is based on HTTP headers, opting in to it may allow an attacker + > to trigger cardinality limits, degrading the usefulness of the metric. - ref: server.port requirement_level: opt_in brief: > Port of the local HTTP server that received the request. note: | - Determined by using the first of the following that applies + See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). + > **Warning** + > Since this attribute is based on HTTP headers, opting in to it may allow an attacker + > to trigger cardinality limits, degrading the usefulness of the metric. - - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. - - Port identifier of the `Host` header - - - id: metric.http.server.request.size + - id: metric.http.server.request.body.size type: metric - metric_name: http.server.request.size - brief: "Measures the size of HTTP request messages (compressed)." + metric_name: http.server.request.body.size + stability: experimental + brief: "Size of HTTP server request bodies." instrument: histogram unit: "By" + note: > + The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and + is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) + header. For requests using transport encoding, this should be the compressed size. extends: metric_attributes.http.server - - id: metric.http.server.response.size + - id: metric.http.server.response.body.size type: metric - metric_name: http.server.response.size - brief: "Measures the size of HTTP response messages (compressed)." + metric_name: http.server.response.body.size + stability: experimental + brief: "Size of HTTP server response bodies." instrument: histogram unit: "By" + note: > + The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and + is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) + header. For requests using transport encoding, this should be the compressed size. extends: metric_attributes.http.server - - id: metric.http.client.duration + - id: metric.http.client.request.duration type: metric - metric_name: http.client.duration - brief: "Measures the duration of outbound HTTP requests." + metric_name: http.client.request.duration + brief: "Duration of HTTP client requests." instrument: histogram unit: "s" + stability: stable extends: metric_attributes.http.client - - id: metric.http.client.request.size + - id: metric.http.client.request.body.size type: metric - metric_name: http.client.request.size - brief: "Measures the size of HTTP request messages (compressed)." + metric_name: http.client.request.body.size + stability: experimental + brief: "Size of HTTP client request bodies." instrument: histogram unit: "By" + note: > + The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and + is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) + header. For requests using transport encoding, this should be the compressed size. extends: metric_attributes.http.client - - id: metric.http.client.response.size + - id: metric.http.client.response.body.size type: metric - metric_name: http.client.response.size - brief: "Measures the size of HTTP response messages (compressed)." + metric_name: http.client.response.body.size + stability: experimental + brief: "Size of HTTP client response bodies." instrument: histogram unit: "By" + note: > + The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and + is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) + header. For requests using transport encoding, this should be the compressed size. extends: metric_attributes.http.client + + - id: metric.http.client.open_connections + type: metric + metric_name: http.client.open_connections + stability: experimental + brief: "Number of outbound HTTP connections that are currently active or idle on the client." + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: http.connection.state + requirement_level: required + - ref: network.peer.address + requirement_level: recommended + - ref: network.protocol.version + requirement_level: recommended + - ref: server.address + requirement_level: required + - ref: server.port + requirement_level: required + brief: > + Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + - ref: url.scheme + requirement_level: opt_in + examples: ["http", "https"] + + - id: metric.http.client.connection.duration + type: metric + metric_name: http.client.connection.duration + stability: experimental + brief: "The duration of the successfully established outbound HTTP connections." + instrument: histogram + unit: "s" + attributes: + - ref: network.peer.address + requirement_level: recommended + - ref: network.protocol.version + requirement_level: recommended + - ref: server.address + requirement_level: required + - ref: server.port + requirement_level: required + brief: > + Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + - ref: url.scheme + requirement_level: opt_in + examples: ["http", "https"] + + - id: metric.http.client.active_requests + type: metric + metric_name: http.client.active_requests + stability: experimental + brief: "Number of active HTTP requests." + instrument: updowncounter + unit: "{request}" + attributes: + - ref: http.request.method + requirement_level: recommended + - ref: server.address + requirement_level: required + - ref: server.port + requirement_level: required + brief: > + Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + - ref: url.scheme + requirement_level: opt_in + examples: ["http", "https"] diff --git a/model/metrics/process-runtime-jvm-metrics-experimental.yaml b/model/metrics/jvm-metrics-experimental.yaml similarity index 67% rename from model/metrics/process-runtime-jvm-metrics-experimental.yaml rename to model/metrics/jvm-metrics-experimental.yaml index 3956368631..4bc7cc7581 100644 --- a/model/metrics/process-runtime-jvm-metrics-experimental.yaml +++ b/model/metrics/jvm-metrics-experimental.yaml @@ -1,15 +1,17 @@ groups: - - id: metric.process.runtime.jvm.memory.init + - id: metric.jvm.memory.init type: metric - metric_name: process.runtime.jvm.memory.init - extends: attributes.process.runtime.jvm.memory + metric_name: jvm.memory.init + stability: experimental + extends: attributes.jvm.memory brief: "Measure of initial memory requested." instrument: updowncounter unit: "By" - - id: metric.process.runtime.jvm.system.cpu.utilization + - id: metric.jvm.system.cpu.utilization type: metric - metric_name: process.runtime.jvm.system.cpu.utilization + metric_name: jvm.system.cpu.utilization + stability: experimental brief: "Recent CPU utilization for the whole system as reported by the JVM." note: > The value range is [0.0,1.0]. @@ -19,9 +21,10 @@ groups: instrument: gauge unit: "1" - - id: metric.process.runtime.jvm.system.cpu.load_1m + - id: metric.jvm.system.cpu.load_1m type: metric - metric_name: process.runtime.jvm.system.cpu.load_1m + metric_name: jvm.system.cpu.load_1m + stability: experimental brief: "Average CPU load of the whole system for the last minute as reported by the JVM." note: > The value range is [0,n], where n is the number of CPU cores - or a negative number if the value is not available. @@ -31,37 +34,44 @@ groups: instrument: gauge unit: "{run_queue_item}" - - id: attributes.process.runtime.jvm.buffer + - id: attributes.jvm.buffer type: attribute_group brief: "Describes JVM buffer metric attributes." + prefix: jvm.buffer attributes: - - ref: pool + - id: pool.name + type: string + stability: experimental + requirement_level: recommended brief: Name of the buffer pool. examples: [ "mapped", "direct" ] note: > Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). - - id: metric.process.runtime.jvm.buffer.usage + - id: metric.jvm.buffer.memory.usage type: metric - metric_name: process.runtime.jvm.buffer.usage - extends: attributes.process.runtime.jvm.buffer + metric_name: jvm.buffer.memory.usage + stability: experimental + extends: attributes.jvm.buffer brief: "Measure of memory used by buffers." instrument: updowncounter unit: "By" - - id: metric.process.runtime.jvm.buffer.limit + - id: metric.jvm.buffer.memory.limit type: metric - metric_name: process.runtime.jvm.buffer.limit - extends: attributes.process.runtime.jvm.buffer + metric_name: jvm.buffer.memory.limit + stability: experimental + extends: attributes.jvm.buffer brief: "Measure of total memory capacity of buffers." instrument: updowncounter unit: "By" - - id: metric.process.runtime.jvm.buffer.count + - id: metric.jvm.buffer.count type: metric - metric_name: process.runtime.jvm.buffer.count - extends: attributes.process.runtime.jvm.buffer + metric_name: jvm.buffer.count + stability: experimental + extends: attributes.jvm.buffer brief: "Number of buffers in the pool." instrument: updowncounter unit: "{buffer}" diff --git a/model/metrics/jvm-metrics.yaml b/model/metrics/jvm-metrics.yaml new file mode 100644 index 0000000000..b0e4224086 --- /dev/null +++ b/model/metrics/jvm-metrics.yaml @@ -0,0 +1,127 @@ +groups: + - id: attributes.jvm.memory + type: attribute_group + brief: "Describes JVM memory metric attributes." + prefix: jvm.memory + attributes: + - ref: jvm.memory.type + requirement_level: recommended + - ref: jvm.memory.pool.name + requirement_level: recommended + brief: Name of the memory pool. + + - id: metric.jvm.memory.used + type: metric + metric_name: jvm.memory.used + extends: attributes.jvm.memory + brief: "Measure of memory used." + instrument: updowncounter + unit: "By" + stability: stable + + - id: metric.jvm.memory.committed + type: metric + metric_name: jvm.memory.committed + extends: attributes.jvm.memory + brief: "Measure of memory committed." + instrument: updowncounter + unit: "By" + stability: stable + + - id: metric.jvm.memory.limit + type: metric + metric_name: jvm.memory.limit + extends: attributes.jvm.memory + brief: "Measure of max obtainable memory." + instrument: updowncounter + unit: "By" + stability: stable + + - id: metric.jvm.memory.used_after_last_gc + type: metric + metric_name: jvm.memory.used_after_last_gc + extends: attributes.jvm.memory + brief: "Measure of memory used, as measured after the most recent garbage collection event on this pool." + instrument: updowncounter + unit: "By" + stability: stable + + - id: metric.jvm.gc.duration + type: metric + metric_name: jvm.gc.duration + brief: "Duration of JVM garbage collection actions." + instrument: histogram + unit: "s" + prefix: jvm.gc + attributes: + - ref: jvm.gc.name + requirement_level: recommended + - ref: jvm.gc.action + requirement_level: recommended + stability: stable + + - id: metric.jvm.thread.count + type: metric + metric_name: jvm.thread.count + brief: "Number of executing platform threads." + instrument: updowncounter + unit: "{thread}" + attributes: + - ref: jvm.thread.daemon + requirement_level: recommended + - ref: jvm.thread.state + requirement_level: recommended + stability: stable + + - id: metric.jvm.class.loaded + type: metric + metric_name: jvm.class.loaded + brief: "Number of classes loaded since JVM start." + instrument: counter + unit: "{class}" + stability: stable + + - id: metric.jvm.class.unloaded + type: metric + metric_name: jvm.class.unloaded + brief: "Number of classes unloaded since JVM start." + instrument: counter + unit: "{class}" + stability: stable + + - id: metric.jvm.class.count + type: metric + metric_name: jvm.class.count + brief: "Number of classes currently loaded." + instrument: updowncounter + unit: "{class}" + stability: stable + + - id: metric.jvm.cpu.count + type: metric + metric_name: jvm.cpu.count + brief: "Number of processors available to the Java virtual machine." + instrument: updowncounter + unit: "{cpu}" + stability: stable + + - id: metric.jvm.cpu.time + type: metric + metric_name: jvm.cpu.time + brief: "CPU time used by the process as reported by the JVM." + instrument: counter + unit: "s" + stability: stable + + - id: metric.jvm.cpu.recent_utilization + type: metric + metric_name: jvm.cpu.recent_utilization + brief: "Recent CPU utilization for the process as reported by the JVM." + note: > + The value range is [0.0,1.0]. + This utilization is not defined as being for the specific interval since last measurement + (unlike `system.cpu.utilization`). + [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()). + instrument: gauge + unit: "1" + stability: stable diff --git a/model/metrics/messaging.yaml b/model/metrics/messaging.yaml new file mode 100644 index 0000000000..03a1a5b44b --- /dev/null +++ b/model/metrics/messaging.yaml @@ -0,0 +1,69 @@ +groups: + - id: metric.messaging.attributes + type: attribute_group + stability: experimental + brief: "Common messaging metrics attributes." + extends: messaging.attributes.common + attributes: + - 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/process-metrics.yaml b/model/metrics/process-metrics.yaml new file mode 100644 index 0000000000..b6e99ed9f0 --- /dev/null +++ b/model/metrics/process-metrics.yaml @@ -0,0 +1,136 @@ +groups: + - id: attributes.process.cpu + prefix: process.cpu + type: attribute_group + brief: "Attributes for process CPU metrics." + attributes: + - id: state + brief: "The CPU state for this data point. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels." + 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 + - id: metric.process.cpu.time + type: metric + metric_name: process.cpu.time + stability: experimental + brief: "Total CPU seconds broken down by different states." + instrument: counter + unit: "s" + attributes: + - ref: process.cpu.state + + - id: metric.process.cpu.utilization + type: metric + metric_name: process.cpu.utilization + stability: experimental + brief: "Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process." + instrument: gauge + unit: "1" + attributes: + - ref: process.cpu.state + + - id: metric.process.memory.usage + type: metric + metric_name: process.memory.usage + stability: experimental + brief: "The amount of physical memory in use." + instrument: updowncounter + unit: "By" + attributes: [] + + - id: metric.process.memory.virtual + type: metric + metric_name: process.memory.virtual + stability: experimental + brief: "The amount of committed virtual memory." + instrument: updowncounter + unit: "By" + attributes: [] + + - id: metric.process.disk.io + type: metric + metric_name: process.disk.io + stability: experimental + prefix: process.disk + brief: "Disk bytes transferred." + instrument: counter + unit: "By" + attributes: + - ref: disk.io.direction + + - id: metric.process.network.io + type: metric + metric_name: process.network.io + stability: experimental + brief: "Network bytes transferred." + instrument: counter + unit: "By" + attributes: + - ref: network.io.direction + + - id: metric.process.thread.count + type: metric + metric_name: process.thread.count + stability: experimental + brief: "Process threads count." + instrument: updowncounter + unit: "{thread}" + + - id: metric.process.open_file_descriptor.count + type: metric + metric_name: process.open_file_descriptor.count + stability: experimental + brief: "Number of file descriptors in use by the process." + instrument: updowncounter + unit: "{count}" + + - id: metric.process.context_switches + type: metric + metric_name: process.context_switches + stability: experimental + brief: "Number of times the process has been context switched." + instrument: counter + unit: "{count}" + attributes: + - id: process.context_switch_type + brief: "Specifies whether the context switches for this data point were voluntary or involuntary." + type: + allow_custom_values: true + members: + - id: voluntary + value: 'voluntary' + stability: experimental + - id: involuntary + value: 'involuntary' + stability: experimental + stability: experimental + - id: metric.process.paging.faults + type: metric + metric_name: process.paging.faults + stability: experimental + brief: "Number of page faults the process has made." + instrument: counter + unit: "{fault}" + attributes: + - id: process.paging.fault_type + brief: "The type of page fault for this data point. Type `major` is for major/hard page faults, and `minor` is for minor/soft page faults." + type: + allow_custom_values: true + members: + - id: major + value: 'major' + stability: experimental + - id: minor + value: 'minor' + stability: experimental + stability: experimental diff --git a/model/metrics/process-runtime-jvm-metrics.yaml b/model/metrics/process-runtime-jvm-metrics.yaml deleted file mode 100644 index 1721b8e956..0000000000 --- a/model/metrics/process-runtime-jvm-metrics.yaml +++ /dev/null @@ -1,134 +0,0 @@ -groups: - - id: attributes.process.runtime.jvm.memory - type: attribute_group - brief: "Describes JVM memory metric attributes." - attributes: - - id: type - type: - allow_custom_values: false - members: - - id: heap - value: 'heap' - brief: 'Heap memory.' - - id: non_heap - value: 'non_heap' - brief: 'Non-heap memory' - requirement_level: recommended - brief: The type of memory. - examples: ["heap", "non_heap"] - - id: pool - type: string - requirement_level: recommended - brief: Name of the memory pool. - examples: ["G1 Old Gen", "G1 Eden space", "G1 Survivor Space"] - note: > - Pool names are generally obtained via - [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - - - id: metric.process.runtime.jvm.memory.usage - type: metric - metric_name: process.runtime.jvm.memory.usage - extends: attributes.process.runtime.jvm.memory - brief: "Measure of memory used." - instrument: updowncounter - unit: "By" - - - id: metric.process.runtime.jvm.memory.committed - type: metric - metric_name: process.runtime.jvm.memory.committed - extends: attributes.process.runtime.jvm.memory - brief: "Measure of memory committed." - instrument: updowncounter - unit: "By" - - - id: metric.process.runtime.jvm.memory.limit - type: metric - metric_name: process.runtime.jvm.memory.limit - extends: attributes.process.runtime.jvm.memory - brief: "Measure of max obtainable memory." - instrument: updowncounter - unit: "By" - - - id: metric.process.runtime.jvm.memory.usage_after_last_gc - type: metric - metric_name: process.runtime.jvm.memory.usage_after_last_gc - extends: attributes.process.runtime.jvm.memory - brief: "Measure of memory used, as measured after the most recent garbage collection event on this pool." - instrument: updowncounter - unit: "By" - - - id: metric.process.runtime.jvm.gc.duration - type: metric - metric_name: process.runtime.jvm.gc.duration - brief: "Duration of JVM garbage collection actions." - instrument: histogram - unit: "s" - attributes: - - id: gc - type: string - requirement_level: recommended - brief: Name of the garbage collector. - examples: ["G1 Young Generation", "G1 Old Generation"] - note: > - Garbage collector name is generally obtained via - [GarbageCollectionNotificationInfo#getGcName()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcName()). - - id: action - type: string - requirement_level: recommended - brief: Name of the garbage collector action. - examples: ["end of minor GC", "end of major GC"] - note: > - Garbage collector action is generally obtained via - [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()). - - - id: metric.process.runtime.jvm.threads.count - type: metric - metric_name: process.runtime.jvm.threads.count - brief: "Number of executing platform threads." - instrument: updowncounter - unit: "{thread}" - attributes: - - id: daemon - brief: "Whether the thread is daemon or not." - type: boolean - requirement_level: recommended - - - id: metric.process.runtime.jvm.classes.loaded - type: metric - metric_name: process.runtime.jvm.classes.loaded - brief: "Number of classes loaded since JVM start." - instrument: counter - unit: "{class}" - - - id: metric.process.runtime.jvm.classes.unloaded - type: metric - metric_name: process.runtime.jvm.classes.unloaded - brief: "Number of classes unloaded since JVM start." - instrument: counter - unit: "{class}" - - - id: metric.process.runtime.jvm.classes.current_loaded - type: metric - metric_name: process.runtime.jvm.classes.current_loaded - brief: "Number of classes currently loaded." - instrument: updowncounter - unit: "{class}" - - - id: metric.process.runtime.jvm.cpu.time - type: metric - metric_name: process.runtime.jvm.cpu.time - brief: "CPU time used by the process as reported by the JVM." - instrument: counter - unit: "s" - - - id: metric.process.runtime.jvm.cpu.recent_utilization - type: metric - metric_name: process.runtime.jvm.cpu.recent_utilization - brief: "Recent CPU utilization for the process as reported by the JVM." - note: > - The value range is [0.0,1.0]. - This utilization is not defined as being for the specific interval since last measurement - (unlike `system.cpu.utilization`). - [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()). - instrument: gauge - unit: "1" diff --git a/model/metrics/rpc-metrics.yaml b/model/metrics/rpc-metrics.yaml new file mode 100644 index 0000000000..aa47588d41 --- /dev/null +++ b/model/metrics/rpc-metrics.yaml @@ -0,0 +1,132 @@ +groups: + # TODO: Should we list the attributes on each metric + # OR leave a single table like it is today? Since all attributes are applied + # to all metrics, the repetition of them bloats the page + - id: attributes.metrics.rpc + type: attribute_group + brief: "Describes RPC metric attributes." + attributes: + - ref: rpc.system + requirement_level: required + - ref: rpc.service + - ref: rpc.method + - ref: network.transport + - ref: network.type + - ref: server.address + - ref: server.port + + # RPC Server metrics + - id: metric.rpc.server.duration + type: metric + metric_name: rpc.server.duration + stability: experimental + brief: Measures the duration of inbound RPC. + instrument: histogram + unit: "ms" + note: | + While streaming RPCs may record this metric as start-of-batch + to end-of-batch, it's hard to interpret in practice. + + **Streaming**: N/A. + + - id: metric.rpc.server.request.size + type: metric + metric_name: rpc.server.request.size + stability: experimental + brief: Measures the size of RPC request messages (uncompressed). + instrument: histogram + unit: "By" + note: | + **Streaming**: Recorded per message in a streaming batch + + - id: metric.rpc.server.response.size + type: metric + metric_name: rpc.server.response.size + stability: experimental + brief: Measures the size of RPC response messages (uncompressed). + instrument: histogram + unit: "By" + note: | + **Streaming**: Recorded per response in a streaming batch + + - id: metric.rpc.server.requests_per_rpc + type: metric + metric_name: rpc.server.requests_per_rpc + stability: experimental + brief: Measures the number of messages received per RPC. + instrument: histogram + unit: "{count}" + note: | + Should be 1 for all non-streaming RPCs. + + **Streaming** : This metric is required for server and client streaming RPCs + + - id: metric.rpc.server.responses_per_rpc + type: metric + metric_name: rpc.server.responses_per_rpc + stability: experimental + brief: Measures the number of messages sent per RPC. + instrument: histogram + unit: "{count}" + note: | + Should be 1 for all non-streaming RPCs. + + **Streaming**: This metric is required for server and client streaming RPCs + + # RPC Client metrics + - id: metric.rpc.client.duration + type: metric + metric_name: rpc.client.duration + stability: experimental + brief: Measures the duration of outbound RPC. + instrument: histogram + unit: "ms" + note: | + While streaming RPCs may record this metric as start-of-batch + to end-of-batch, it's hard to interpret in practice. + + **Streaming**: N/A. + + - id: metric.rpc.client.request.size + type: metric + metric_name: rpc.client.request.size + stability: experimental + brief: Measures the size of RPC request messages (uncompressed). + instrument: histogram + unit: "By" + note: | + **Streaming**: Recorded per message in a streaming batch + + - id: metric.rpc.client.response.size + type: metric + metric_name: rpc.client.response.size + stability: experimental + brief: Measures the size of RPC response messages (uncompressed). + instrument: histogram + unit: "By" + note: | + **Streaming**: Recorded per response in a streaming batch + + - id: metric.rpc.client.requests_per_rpc + type: metric + metric_name: rpc.client.requests_per_rpc + stability: experimental + brief: Measures the number of messages received per RPC. + instrument: histogram + unit: "{count}" + note: | + Should be 1 for all non-streaming RPCs. + + **Streaming**: This metric is required for server and client streaming RPCs + + - id: metric.rpc.client.responses_per_rpc + type: metric + metric_name: rpc.client.responses_per_rpc + stability: experimental + brief: Measures the number of messages sent per RPC. + instrument: histogram + unit: "{count}" + note: | + Should be 1 for all non-streaming RPCs. + + **Streaming**: This metric is required for server and client streaming RPCs diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml new file mode 100644 index 0000000000..7d0ab1eb96 --- /dev/null +++ b/model/metrics/system-metrics.yaml @@ -0,0 +1,342 @@ +groups: + # system.cpu.* metrics + - id: metric.system.cpu.time + type: metric + metric_name: system.cpu.time + stability: experimental + brief: "Seconds each logical CPU spent on each mode" + 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: system.cpu.logical_number + + - id: metric.system.cpu.utilization + type: metric + metric_name: system.cpu.utilization + stability: experimental + brief: "Difference in system.cpu.time since the last measurement, divided by the elapsed time and number of logical CPUs" + 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: system.cpu.logical_number + + - id: metric.system.cpu.frequency + type: metric + metric_name: system.cpu.frequency + stability: experimental + brief: "Reports the current frequency of the CPU in Hz" + instrument: gauge + unit: "{Hz}" + attributes: + - ref: system.cpu.logical_number + + - id: metric.system.cpu.physical.count + type: metric + metric_name: system.cpu.physical.count + stability: experimental + brief: "Reports the number of actual physical processor cores on the hardware" + instrument: updowncounter + unit: "{cpu}" + attributes: [] + + - id: metric.system.cpu.logical.count + type: metric + metric_name: system.cpu.logical.count + stability: experimental + brief: "Reports the number of logical (virtual) processor cores created by the operating system to manage multitasking" + instrument: updowncounter + unit: "{cpu}" + attributes: [] + + # sytem.memory.* metrics + - id: metric.system.memory.usage + type: metric + metric_name: system.memory.usage + stability: experimental + brief: "Reports memory in use by state." + note: | + The sum over all `system.memory.state` values SHOULD equal the total memory + available on the system, that is `system.memory.limit`. + instrument: updowncounter + unit: "By" + attributes: + - ref: system.memory.state + + - id: metric.system.memory.limit + type: metric + metric_name: system.memory.limit + stability: experimental + brief: "Total memory available in the system." + note: | + Its value SHOULD equal the sum of `system.memory.state` over all states. + instrument: updowncounter + unit: "By" + attributes: [] + + - id: metric.system.memory.shared + type: metric + metric_name: system.memory.shared + stability: experimental + brief: "Shared memory used (mostly by tmpfs)." + note: | + Equivalent of `shared` from [`free` command](https://man7.org/linux/man-pages/man1/free.1.html) or + `Shmem` from [`/proc/meminfo`](https://man7.org/linux/man-pages/man5/proc.5.html)" + instrument: updowncounter + unit: "By" + + - id: metric.system.memory.utilization + type: metric + metric_name: system.memory.utilization + stability: experimental + brief: "" + instrument: gauge + unit: "1" + attributes: + - ref: system.memory.state + + # system.paging.* metrics + - id: metric.system.paging.usage + type: metric + metric_name: system.paging.usage + stability: experimental + brief: "Unix swap or windows pagefile usage" + instrument: updowncounter + unit: "By" + attributes: + - ref: system.paging.state + + - id: metric.system.paging.utilization + type: metric + metric_name: system.paging.utilization + stability: experimental + brief: "" + instrument: gauge + unit: "1" + attributes: + - ref: system.paging.state + + - id: metric.system.paging.faults + type: metric + metric_name: system.paging.faults + stability: experimental + brief: "" + instrument: counter + unit: "{fault}" + attributes: + - ref: system.paging.type + + - id: metric.system.paging.operations + type: metric + metric_name: system.paging.operations + stability: experimental + brief: "" + instrument: counter + unit: "{operation}" + attributes: + - ref: system.paging.type + - ref: system.paging.direction + + # system.disk.* metrics + - id: metric.system.disk.io + type: metric + metric_name: system.disk.io + stability: experimental + brief: "" + instrument: counter + unit: "By" + attributes: + - ref: system.device + - ref: disk.io.direction + + - id: metric.system.disk.operations + type: metric + metric_name: system.disk.operations + stability: experimental + brief: "" + instrument: counter + unit: "{operation}" + attributes: + - ref: system.device + - ref: disk.io.direction + + - id: metric.system.disk.io_time + type: metric + metric_name: system.disk.io_time + stability: experimental + brief: "Time disk spent activated" + instrument: counter + unit: "s" + note: | + The real elapsed time ("wall clock") used in the I/O path (time from operations running in parallel are not counted). Measured as: + + - Linux: Field 13 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) + - Windows: The complement of + ["Disk\% Idle Time"](https://learn.microsoft.com/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained) + performance counter: `uptime * (100 - "Disk\% Idle Time") / 100` + attributes: + - ref: system.device + + - id: metric.system.disk.operation_time + type: metric + metric_name: system.disk.operation_time + stability: experimental + brief: "Sum of the time each operation took to complete" + instrument: counter + unit: "s" + note: | + Because it is the sum of time each request took, parallel-issued requests each contribute to make the count grow. Measured as: + + - Linux: Fields 7 & 11 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) + - Windows: "Avg. Disk sec/Read" perf counter multiplied by "Disk Reads/sec" perf counter (similar for Writes) + attributes: + - ref: system.device + - ref: disk.io.direction + + - id: metric.system.disk.merged + type: metric + metric_name: system.disk.merged + stability: experimental + brief: "" + instrument: counter + unit: "{operation}" + attributes: + - ref: system.device + - ref: disk.io.direction + + # system.filesystem.* metrics + - id: metric.system.filesystem.usage + type: metric + metric_name: system.filesystem.usage + stability: experimental + brief: "" + instrument: updowncounter + unit: "By" + attributes: + - ref: system.device + - ref: system.filesystem.state + - ref: system.filesystem.type + - ref: system.filesystem.mode + - ref: system.filesystem.mountpoint + + - id: metric.system.filesystem.utilization + type: metric + metric_name: system.filesystem.utilization + stability: experimental + brief: "" + instrument: gauge + unit: "1" + attributes: + - ref: system.device + - ref: system.filesystem.state + - ref: system.filesystem.type + - ref: system.filesystem.mode + - ref: system.filesystem.mountpoint + + # system.network.* metrics + - id: metric.system.network.dropped + type: metric + metric_name: system.network.dropped + stability: experimental + brief: "Count of packets that are dropped or discarded even though there was no error" + instrument: counter + unit: "{packet}" + note: | + Measured as: + + - Linux: the `drop` column in `/proc/dev/net` ([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)) + - Windows: [`InDiscards`/`OutDiscards`](https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) + from [`GetIfEntry2`](https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2) + attributes: + - ref: system.device + - ref: network.io.direction + + - id: metric.system.network.packets + type: metric + metric_name: system.network.packets + stability: experimental + brief: "" + instrument: counter + unit: "{packet}" + attributes: + - ref: system.device + - ref: network.io.direction + + - id: metric.system.network.errors + type: metric + metric_name: system.network.errors + stability: experimental + brief: "Count of network errors detected" + instrument: counter + unit: "{error}" + note: | + Measured as: + + - Linux: the `errs` column in `/proc/dev/net` ([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)). + - Windows: [`InErrors`/`OutErrors`](https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) + from [`GetIfEntry2`](https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2). + attributes: + - ref: system.device + - ref: network.io.direction + + - id: metric.system.network.io + type: metric + metric_name: system.network.io + stability: experimental + brief: "" + instrument: counter + unit: "By" + attributes: + - ref: system.device + - ref: network.io.direction + + - id: metric.system.network.connections + type: metric + metric_name: system.network.connections + stability: experimental + brief: "" + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: system.device + - ref: system.network.state + - ref: network.transport + + # system.process.* metrics + - id: metric.system.process.count + type: metric + metric_name: system.process.count + stability: experimental + brief: "Total number of processes in each state" + instrument: updowncounter + unit: "{process}" + attributes: + - ref: system.process.status + + - id: metric.system.process.created + type: metric + metric_name: system.process.created + stability: experimental + brief: "Total number of processes created over uptime of the host" + instrument: counter + unit: "{process}" + attributes: [] + + # system.linux.* metrics + - id: metric.system.linux.memory.available + type: metric + metric_name: system.linux.memory.available + stability: experimental + brief: "An estimate of how much memory is available for starting new applications, without causing swapping" + note: | + This is an alternative to `system.memory.usage` metric with `state=free`. + Linux starting from 3.14 exports "available" memory. It takes "free" memory as a baseline, and then factors in kernel-specific values. + This is supposed to be more accurate than just "free" memory. + For reference, see the calculations [here](https://superuser.com/a/980821). + See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html). + instrument: updowncounter + unit: "By" + attributes: [] diff --git a/model/network.yaml b/model/network.yaml new file mode 100644 index 0000000000..7e1ee396f6 --- /dev/null +++ b/model/network.yaml @@ -0,0 +1,28 @@ +groups: + - id: network-core + prefix: network + type: attribute_group + brief: > + These attributes may be used for any network related operation. + attributes: + - ref: network.transport + - ref: network.type + - ref: network.protocol.name + - ref: network.protocol.version + - ref: network.peer.address + - ref: network.peer.port + - ref: network.local.address + - ref: network.local.port + + - id: network-connection-and-carrier + prefix: network + type: attribute_group + brief: > + These attributes may be used for any network related operation. + attributes: + - ref: network.connection.type + - ref: network.connection.subtype + - ref: network.carrier.name + - ref: network.carrier.mcc + - ref: network.carrier.mnc + - ref: network.carrier.icc diff --git a/model/registry/android.yaml b/model/registry/android.yaml new file mode 100644 index 0000000000..cfdcac8a46 --- /dev/null +++ b/model/registry/android.yaml @@ -0,0 +1,15 @@ +groups: + - id: registry.android + prefix: android + type: attribute_group + brief: > + The Android platform on which the Android application is running. + attributes: + - id: os.api_level + type: string + stability: experimental + brief: > + Uniquely identifies the framework API revision offered by a version + (`os.version`) of the android operating system. More information can be found + [here](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels). + examples: ['33', '32'] diff --git a/model/registry/aspnetcore.yaml b/model/registry/aspnetcore.yaml new file mode 100644 index 0000000000..0c93fc1aee --- /dev/null +++ b/model/registry/aspnetcore.yaml @@ -0,0 +1,90 @@ +groups: + - id: registry.aspnetcore + prefix: aspnetcore + type: attribute_group + brief: ASP.NET Core attributes + attributes: + - id: rate_limiting.policy + type: string + brief: Rate limiting policy name. + stability: stable + examples: ["fixed", "sliding", "token"] + - id: rate_limiting.result + type: + allow_custom_values: true + members: + - id: acquired + value: 'acquired' + brief: "Lease was acquired" + stability: stable + - id: endpoint_limiter + value: 'endpoint_limiter' + brief: "Lease request was rejected by the endpoint limiter" + stability: stable + - id: global_limiter + value: 'global_limiter' + brief: "Lease request was rejected by the global limiter" + stability: stable + - id: request_canceled + value: 'request_canceled' + brief: "Lease request was canceled" + stability: stable + stability: stable + brief: Rate-limiting result, shows whether the lease was acquired or contains a rejection reason + examples: ["acquired", "request_canceled"] + requirement_level: required + - id: routing.is_fallback + type: boolean + stability: stable + brief: A value that indicates whether the matched route is a fallback route. + examples: [true] + - id: diagnostics.handler.type + type: string + stability: stable + brief: Full type name of the [`IExceptionHandler`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.diagnostics.iexceptionhandler) + implementation that handled the exception. + examples: ["Contoso.MyHandler"] + requirement_level: + conditionally_required: if and only if the exception was handled by this handler. + - id: request.is_unhandled + type: boolean + stability: stable + brief: Flag indicating if request was handled by the application pipeline. + examples: [true] + - id: routing.match_status + type: + allow_custom_values: true + members: + - id: success + value: 'success' + brief: 'Match succeeded' + stability: stable + - id: failure + value: 'failure' + brief: 'Match failed' + stability: stable + stability: stable + brief: Match result - success or failure + examples: ["success", "failure"] + - id: diagnostics.exception.result + type: + members: + - id: handled + value: 'handled' + brief: "Exception was handled by the exception handling middleware." + stability: stable + - id: unhandled + value: 'unhandled' + brief: "Exception was not handled by the exception handling middleware." + stability: stable + - id: skipped + value: 'skipped' + brief: "Exception handling was skipped because the response had started." + stability: stable + - id: aborted + value: 'aborted' + brief: "Exception handling didn't run because the request was aborted." + stability: stable + stability: stable + brief: ASP.NET Core exception middleware handling result + examples: ["handled", "unhandled"] diff --git a/model/registry/aws.yaml b/model/registry/aws.yaml new file mode 100644 index 0000000000..90bb10b853 --- /dev/null +++ b/model/registry/aws.yaml @@ -0,0 +1,472 @@ +groups: + - id: registry.aws + prefix: aws + type: attribute_group + brief: > + This document defines generic attributes for AWS services. + attributes: + - id: request_id + type: string + stability: experimental + brief: "The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`." + examples: + - 79b9da39-b7ae-508a-a6bc-864b2829c622 + - C9ER4AJX75574TDJ + - id: registry.aws.dynamodb + prefix: aws.dynamodb + type: attribute_group + brief: > + This document defines attributes for AWS DynamoDB. + attributes: + - id: table_names + type: string[] + stability: experimental + brief: The keys in the `RequestItems` object field. + examples: + - Users + - Cats + - id: consumed_capacity + type: string[] + stability: experimental + brief: "The JSON-serialized value of each item in the `ConsumedCapacity` response field." + examples: + - '{ + "CapacityUnits": number, + "GlobalSecondaryIndexes": { + "string" : { + "CapacityUnits": number, + "ReadCapacityUnits": number, + "WriteCapacityUnits": number + } + }, + "LocalSecondaryIndexes": { + "string" : { + "CapacityUnits": number, + "ReadCapacityUnits": number, + "WriteCapacityUnits": number + } + }, + "ReadCapacityUnits": number, + "Table": { + "CapacityUnits": number, + "ReadCapacityUnits": number, + "WriteCapacityUnits": number + }, + "TableName": "string", + "WriteCapacityUnits": number + }' + - id: item_collection_metrics + type: string + stability: experimental + brief: "The JSON-serialized value of the `ItemCollectionMetrics` response field." + examples: + - '{ + "string" : [ + { + "ItemCollectionKey": { + "string" : { + "B": blob, + "BOOL": boolean, + "BS": [ blob ], + "L": [ + "AttributeValue" + ], + "M": { + "string" : "AttributeValue" + }, + "N": "string", + "NS": [ "string" ], + "NULL": boolean, + "S": "string", + "SS": [ "string" ] + } + }, + "SizeEstimateRangeGB": [ number ] + } + ] + }' + - id: provisioned_read_capacity + type: double + stability: experimental + brief: "The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter." + examples: + - 1.0 + - 2.0 + - id: provisioned_write_capacity + type: double + stability: experimental + brief: "The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter." + examples: + - 1.0 + - 2.0 + - id: consistent_read + type: boolean + stability: experimental + brief: "The value of the `ConsistentRead` request parameter." + - id: projection + type: string + stability: experimental + brief: "The value of the `ProjectionExpression` request parameter." + examples: + - Title + - Title, Price, Color + - Title, Description, RelatedItems, ProductReviews + - id: limit + type: int + stability: experimental + brief: "The value of the `Limit` request parameter." + examples: + - 10 + - id: attributes_to_get + type: string[] + stability: experimental + brief: "The value of the `AttributesToGet` request parameter." + examples: + - lives + - id + - id: index_name + type: string + stability: experimental + brief: "The value of the `IndexName` request parameter." + examples: + - name_to_group + - id: select + type: string + stability: experimental + brief: "The value of the `Select` request parameter." + examples: + - ALL_ATTRIBUTES + - COUNT + - id: global_secondary_indexes + type: string[] + stability: experimental + brief: "The JSON-serialized value of each item of the `GlobalSecondaryIndexes` request field" + examples: + - '{ + "IndexName": "string", + "KeySchema": [ + { + "AttributeName": "string", + "KeyType": "string" + } + ], + "Projection": { + "NonKeyAttributes": [ "string" ], + "ProjectionType": "string" + }, + "ProvisionedThroughput": { + "ReadCapacityUnits": number, + "WriteCapacityUnits": number + } + }' + - id: local_secondary_indexes + type: string[] + stability: experimental + brief: "The JSON-serialized value of each item of the `LocalSecondaryIndexes` request field." + examples: + - '{ + "IndexArn": "string", + "IndexName": "string", + "IndexSizeBytes": number, + "ItemCount": number, + "KeySchema": [ + { + "AttributeName": "string", + "KeyType": "string" + } + ], + "Projection": { + "NonKeyAttributes": [ "string" ], + "ProjectionType": "string" + } + }' + - id: exclusive_start_table + type: string + stability: experimental + brief: "The value of the `ExclusiveStartTableName` request parameter." + examples: + - Users + - CatsTable + - id: table_count + type: int + stability: experimental + brief: "The number of items in the `TableNames` response parameter." + examples: + - 20 + - id: scan_forward + type: boolean + stability: experimental + brief: "The value of the `ScanIndexForward` request parameter." + - id: segment + type: int + stability: experimental + brief: "The value of the `Segment` request parameter." + examples: + - 10 + - id: total_segments + type: int + stability: experimental + brief: "The value of the `TotalSegments` request parameter." + examples: + - 100 + - id: count + type: int + stability: experimental + brief: "The value of the `Count` response parameter." + examples: + - 10 + - id: scanned_count + type: int + stability: experimental + brief: "The value of the `ScannedCount` response parameter." + examples: + - 50 + - id: attribute_definitions + type: string[] + stability: experimental + brief: "The JSON-serialized value of each item in the `AttributeDefinitions` request field." + examples: + - '{ + "AttributeName": "string", + "AttributeType": "string" + }' + - id: global_secondary_index_updates + type: string[] + stability: experimental + brief: "The JSON-serialized value of each item in the `GlobalSecondaryIndexUpdates` request field." + examples: + - '{ + "Create": { + "IndexName": "string", + "KeySchema": [ + { + "AttributeName": "string", + "KeyType": "string" + } + ], + "Projection": { + "NonKeyAttributes": [ "string" ], + "ProjectionType": "string" + }, + "ProvisionedThroughput": { + "ReadCapacityUnits": number, + "WriteCapacityUnits": number + } + }' + - id: registry.aws.ecs + prefix: aws.ecs + type: attribute_group + brief: > + This document defines attributes for AWS Elastic Container Service (ECS). + attributes: + - id: container.arn + type: string + stability: experimental + brief: > + The Amazon Resource Name (ARN) of an [ECS container instance](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html). + examples: ['arn:aws:ecs:us-west-1:123456789123:container/32624152-9086-4f0e-acae-1a75b14fe4d9'] + - id: cluster.arn + type: string + stability: experimental + brief: > + The ARN of an [ECS cluster](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/clusters.html). + examples: ['arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster'] + - id: launchtype + type: + allow_custom_values: true + members: + - id: ec2 + value: "ec2" + stability: experimental + - id: fargate + value: "fargate" + stability: experimental + stability: experimental + brief: > + The [launch type](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_types.html) for an ECS task. + - id: task.arn + type: string + stability: experimental + brief: > + The ARN of a running [ECS task](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-account-settings.html#ecs-resource-ids). + examples: [ + 'arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b', + 'arn:aws:ecs:us-west-1:123456789123:task/my-cluster/task-id/23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd' + ] + - id: task.family + type: string + stability: experimental + brief: > + The family name of the [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) used to create the ECS task. + examples: ['opentelemetry-family'] + - id: task.id + type: string + stability: experimental + brief: > + The ID of a running ECS task. The ID MUST be extracted from `task.arn`. + requirement_level: + conditionally_required: If and only if `task.arn` is populated. + examples: [ '10838bed-421f-43ef-870a-f43feacbbb5b', '23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd' ] + - id: task.revision + type: string + stability: experimental + brief: > + The revision for the task definition used to create the ECS task. + examples: ["8", "26"] + - id: registry.aws.eks + prefix: aws.eks + type: attribute_group + brief: > + This document defines attributes for AWS Elastic Kubernetes Service (EKS). + attributes: + - id: cluster.arn + type: string + stability: experimental + brief: > + The ARN of an EKS cluster. + examples: ['arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster'] + - id: registry.aws.log + prefix: aws.log + type: attribute_group + brief: > + This document defines attributes for AWS Logs. + attributes: + - id: group.names + type: string[] + stability: experimental + brief: > + The name(s) of the AWS log group(s) an application is writing to. + examples: ['/aws/lambda/my-function', 'opentelemetry-service'] + note: > + Multiple log groups must be supported for cases like multi-container applications, + where a single application has sidecar containers, and each write to their own log + group. + - id: group.arns + type: string[] + stability: experimental + brief: > + The Amazon Resource Name(s) (ARN) of the AWS log group(s). + examples: ['arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:*'] + note: > + See the + [log group ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). + - id: stream.names + type: string[] + stability: experimental + brief: > + The name(s) of the AWS log stream(s) an application is writing to. + examples: ['logs/main/10838bed-421f-43ef-870a-f43feacbbb5b'] + - id: stream.arns + type: string[] + stability: experimental + brief: > + The ARN(s) of the AWS log stream(s). + examples: ['arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:log-stream:logs/main/10838bed-421f-43ef-870a-f43feacbbb5b'] + note: > + See the + [log stream ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). + One log group can contain several log streams, so these ARNs necessarily identify both a log + group and a log stream. + + - id: registry.aws.lambda + prefix: aws.lambda + type: attribute_group + brief: > + This document defines attributes for AWS Lambda. + attributes: + - id: invoked_arn + type: string + stability: experimental + brief: > + The full invoked ARN as provided on the `Context` passed to the function + (`Lambda-Runtime-Invoked-Function-Arn` header on the `/runtime/invocation/next` applicable). + note: This may be different from `cloud.resource_id` if an alias is involved. + examples: ['arn:aws:lambda:us-east-1:123456:function:myfunction:myalias'] + - id: registry.aws.s3 + prefix: aws.s3 + type: attribute_group + brief: > + This document defines attributes for AWS S3. + attributes: + - id: bucket + type: string + stability: experimental + brief: "The S3 bucket name the request refers to. Corresponds to the `--bucket` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations." + examples: + - some-bucket-name + note: | + The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter. + This applies to almost all S3 operations except `list-buckets`. + - id: key + type: string + stability: experimental + brief: "The S3 object key the request refers to. Corresponds to the `--key` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations." + examples: + - someFile.yml + note: | + The `key` attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter. + This applies in particular to the following operations: + + - [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) + - [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) + - [get-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-object.html) + - [head-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/head-object.html) + - [put-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-object.html) + - [restore-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html) + - [select-object-content](https://docs.aws.amazon.com/cli/latest/reference/s3api/select-object-content.html) + - [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html) + - [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html) + - [create-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/create-multipart-upload.html) + - [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html) + - [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) + - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) + - id: copy_source + type: string + stability: experimental + brief: "The source object (in the form `bucket`/`key`) for the copy operation." + examples: + - someFile.yml + note: | + The `copy_source` attribute applies to S3 copy operations and corresponds to the `--copy-source` parameter + of the [copy-object operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html). + This applies in particular to the following operations: + + - [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) + - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) + - id: upload_id + type: string + stability: experimental + brief: "Upload ID that identifies the multipart upload." + examples: + - 'dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ' + note: | + The `upload_id` attribute applies to S3 multipart-upload operations and corresponds to the `--upload-id` parameter + of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) multipart operations. + This applies in particular to the following operations: + + - [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html) + - [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html) + - [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html) + - [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) + - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) + - id: delete + type: string + stability: experimental + brief: "The delete request container that specifies the objects to be deleted." + examples: + - 'Objects=[{Key=string,VersionId=string},{Key=string,VersionId=string}],Quiet=boolean' + note: | + The `delete` attribute is only applicable to the [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) operation. + The `delete` attribute corresponds to the `--delete` parameter of the + [delete-objects operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-objects.html). + - id: part_number + type: int + stability: experimental + brief: "The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000." + examples: + - 3456 + note: | + The `part_number` attribute is only applicable to the [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) + and [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) operations. + The `part_number` attribute corresponds to the `--part-number` parameter of the + [upload-part operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html). diff --git a/model/registry/browser.yaml b/model/registry/browser.yaml new file mode 100644 index 0000000000..fad84c9787 --- /dev/null +++ b/model/registry/browser.yaml @@ -0,0 +1,51 @@ +groups: + - id: registry.browser + prefix: browser + type: attribute_group + brief: > + The web browser attributes + attributes: + - id: brands + type: string[] + stability: experimental + brief: 'Array of brand name and version separated by a space' + note: > + This value is intended to be taken from the + [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) + (`navigator.userAgentData.brands`). + examples: [ " Not A;Brand 99", "Chromium 99", "Chrome 99" ] + - id: platform + type: string + stability: experimental + brief: 'The platform on which the browser is running' + note: > + This value is intended to be taken from the + [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) + (`navigator.userAgentData.platform`). If unavailable, the legacy + `navigator.platform` API SHOULD NOT be used instead and this attribute + SHOULD be left unset in order for the values to be consistent. + + The list of possible values is defined in the + [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). + Note that some (but not all) of these values can overlap with values + in the [`os.type` and `os.name` attributes](./os.md). + However, for consistency, the values in the `browser.platform` attribute + should capture the exact value that the user agent provides. + examples: ['Windows', 'macOS', 'Android'] + - id: mobile + type: boolean + stability: experimental + brief: 'A boolean that is true if the browser is running on a mobile device' + note: > + This value is intended to be taken from the + [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) + (`navigator.userAgentData.mobile`). If unavailable, this attribute + SHOULD be left unset. + - id: language + type: string + stability: experimental + brief: 'Preferred language of the user using the browser' + note: > + This value is intended to be taken from the Navigator API + `navigator.language`. + examples: ["en", "en-US", "fr", "fr-FR"] diff --git a/model/client.yaml b/model/registry/client.yaml similarity index 53% rename from model/client.yaml rename to model/registry/client.yaml index 1b54ced8cc..3b17ed8b4e 100644 --- a/model/client.yaml +++ b/model/registry/client.yaml @@ -1,5 +1,5 @@ groups: - - id: client + - id: registry.client prefix: client type: attribute_group brief: > @@ -7,32 +7,22 @@ groups: where there is one side that initiates the connection (the client is the side that initiates the connection). This covers all TCP network interactions since TCP is connection-based and one side initiates the connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the - protocol / API does not expose a clear notion of client and server). + protocol / API doesn't expose a clear notion of client and server). This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS. attributes: - id: address + stability: stable type: string - brief: Client address - unix domain socket name, IPv4 or IPv6 address. + brief: "Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name." note: > When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent - client address behind any intermediaries (e.g. proxies) if it's available. - examples: ['/tmp/my.sock', '10.1.2.80'] + the client address behind any intermediaries, for example proxies, if it's available. + examples: ['client.example.com', '10.1.2.80', '/tmp/my.sock'] - id: port + stability: stable type: int - brief: 'Client port number' + brief: Client port number. examples: [65123] note: > When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent - client port behind any intermediaries (e.g. proxies) if it's available. - - id: socket.address - type: string - brief: Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. - examples: ['/tmp/my.sock', '127.0.0.1'] - requirement_level: - recommended: If different than `client.address`. - - id: socket.port - type: int - brief: 'Immediate client peer port number' - examples: [35555] - requirement_level: - recommended: If different than `client.port`. + the client port behind any intermediaries, for example proxies, if it's available. diff --git a/model/registry/cloud.yaml b/model/registry/cloud.yaml new file mode 100644 index 0000000000..1fa9ba3982 --- /dev/null +++ b/model/registry/cloud.yaml @@ -0,0 +1,222 @@ +groups: + - id: registry.cloud + prefix: cloud + type: attribute_group + brief: > + A cloud environment (e.g. GCP, Azure, AWS). + attributes: + - id: provider + type: + allow_custom_values: true + members: + - id: 'alibaba_cloud' + value: 'alibaba_cloud' + brief: 'Alibaba Cloud' + stability: experimental + - id: 'aws' + value: 'aws' + brief: 'Amazon Web Services' + stability: experimental + - id: 'azure' + value: 'azure' + brief: 'Microsoft Azure' + stability: experimental + - id: 'gcp' + value: 'gcp' + brief: 'Google Cloud Platform' + stability: experimental + - id: 'heroku' + value: 'heroku' + brief: 'Heroku Platform as a Service' + stability: experimental + - id: 'ibm_cloud' + value: 'ibm_cloud' + brief: 'IBM Cloud' + stability: experimental + - id: 'tencent_cloud' + value: 'tencent_cloud' + brief: 'Tencent Cloud' + stability: experimental + stability: experimental + brief: > + Name of the cloud provider. + - id: account.id + type: string + stability: experimental + brief: > + The cloud account ID the resource is assigned to. + examples: ['111111111111', 'opentelemetry'] + - id: region + type: string + stability: experimental + brief: > + The geographical region the resource is running. + note: > + Refer to your provider's docs to see the available regions, for example + [Alibaba Cloud regions](https://www.alibabacloud.com/help/doc-detail/40654.htm), + [AWS regions](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/), + [Azure regions](https://azure.microsoft.com/global-infrastructure/geographies/), + [Google Cloud regions](https://cloud.google.com/about/locations), + or [Tencent Cloud regions](https://www.tencentcloud.com/document/product/213/6091). + examples: ['us-central1', 'us-east-1'] + - id: resource_id + type: string + stability: experimental + brief: > + Cloud provider-specific native identifier of the monitored cloud resource + (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, + a [fully qualified resource ID](https://learn.microsoft.com/rest/api/resources/resources/get-by-id) on Azure, + a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) + note: | + On some cloud providers, it may not be possible to determine the full ID at startup, + so it may be necessary to set `cloud.resource_id` as a span attribute instead. + + The exact value to use for `cloud.resource_id` depends on the cloud provider. + The following well-known definitions MUST be used if you set this attribute and they apply: + + * **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). + Take care not to use the "invoked ARN" directly but replace any + [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) + with the resolved function version, as the same runtime instance may be invokable with + multiple different aliases. + * **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) + * **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/rest/api/resources/resources/get-by-id) of the invoked function, + *not* the function app, having the form + `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/`. + This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share + a TracerProvider. + examples: + - 'arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function' + - '//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID' + - '/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/' + - id: availability_zone + type: string + stability: experimental + brief: > + Cloud regions often have multiple, isolated locations known as zones + to increase availability. Availability zone represents the + zone where the resource is running. + note: > + Availability zones are called "zones" on Alibaba Cloud and Google Cloud. + examples: ['us-east-1c'] + - id: platform + type: + allow_custom_values: true + members: + - id: alibaba_cloud_ecs + value: 'alibaba_cloud_ecs' + brief: Alibaba Cloud Elastic Compute Service + stability: experimental + - id: alibaba_cloud_fc + value: 'alibaba_cloud_fc' + brief: Alibaba Cloud Function Compute + stability: experimental + - id: alibaba_cloud_openshift + value: 'alibaba_cloud_openshift' + brief: Red Hat OpenShift on Alibaba Cloud + stability: experimental + - id: aws_ec2 + value: 'aws_ec2' + brief: AWS Elastic Compute Cloud + stability: experimental + - id: aws_ecs + value: 'aws_ecs' + brief: AWS Elastic Container Service + stability: experimental + - id: aws_eks + value: 'aws_eks' + brief: AWS Elastic Kubernetes Service + stability: experimental + - id: aws_lambda + value: 'aws_lambda' + brief: AWS Lambda + stability: experimental + - id: aws_elastic_beanstalk + value: 'aws_elastic_beanstalk' + brief: AWS Elastic Beanstalk + stability: experimental + - id: aws_app_runner + value: 'aws_app_runner' + brief: AWS App Runner + stability: experimental + - id: aws_openshift + value: 'aws_openshift' + brief: Red Hat OpenShift on AWS (ROSA) + stability: experimental + - id: azure_vm + value: 'azure_vm' + brief: Azure Virtual Machines + stability: experimental + - id: azure_container_apps + value: 'azure_container_apps' + brief: Azure Container Apps + stability: experimental + - id: azure_container_instances + value: 'azure_container_instances' + brief: Azure Container Instances + stability: experimental + - id: azure_aks + value: 'azure_aks' + brief: Azure Kubernetes Service + stability: experimental + - id: azure_functions + value: 'azure_functions' + brief: Azure Functions + stability: experimental + - id: azure_app_service + value: 'azure_app_service' + brief: Azure App Service + stability: experimental + - id: azure_openshift + value: 'azure_openshift' + brief: Azure Red Hat OpenShift + stability: experimental + - id: gcp_bare_metal_solution + value: 'gcp_bare_metal_solution' + brief: Google Bare Metal Solution (BMS) + stability: experimental + - id: gcp_compute_engine + value: 'gcp_compute_engine' + brief: Google Cloud Compute Engine (GCE) + stability: experimental + - id: gcp_cloud_run + value: 'gcp_cloud_run' + brief: Google Cloud Run + stability: experimental + - id: gcp_kubernetes_engine + value: 'gcp_kubernetes_engine' + brief: Google Cloud Kubernetes Engine (GKE) + stability: experimental + - id: gcp_cloud_functions + value: 'gcp_cloud_functions' + brief: Google Cloud Functions (GCF) + stability: experimental + - id: gcp_app_engine + value: 'gcp_app_engine' + brief: Google Cloud App Engine (GAE) + stability: experimental + - id: gcp_openshift + value: 'gcp_openshift' + brief: Red Hat OpenShift on Google Cloud + stability: experimental + - id: ibm_cloud_openshift + value: 'ibm_cloud_openshift' + brief: Red Hat OpenShift on IBM Cloud + stability: experimental + - id: tencent_cloud_cvm + value: 'tencent_cloud_cvm' + brief: Tencent Cloud Cloud Virtual Machine (CVM) + stability: experimental + - id: tencent_cloud_eks + value: 'tencent_cloud_eks' + brief: Tencent Cloud Elastic Kubernetes Service (EKS) + stability: experimental + - id: tencent_cloud_scf + value: 'tencent_cloud_scf' + brief: Tencent Cloud Serverless Cloud Function (SCF) + stability: experimental + stability: experimental + brief: > + The cloud platform in use. + note: > + The prefix of the service SHOULD match the one specified in `cloud.provider`. diff --git a/model/registry/cloudevents.yaml b/model/registry/cloudevents.yaml new file mode 100644 index 0000000000..4da702f8a8 --- /dev/null +++ b/model/registry/cloudevents.yaml @@ -0,0 +1,37 @@ +groups: + - id: registry.cloudevents + prefix: cloudevents + type: attribute_group + brief: > + This document defines attributes for CloudEvents. + attributes: + - id: event_id + type: string + stability: experimental + brief: > + The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event. + examples: ['123e4567-e89b-12d3-a456-426614174000', '0001'] + - id: event_source + type: string + stability: experimental + brief: > + The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened. + examples: ['https://github.com/cloudevents', '/cloudevents/spec/pull/123', 'my-service' ] + - id: event_spec_version + type: string + stability: experimental + brief: > + The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses. + examples: '1.0' + - id: event_type + type: string + stability: experimental + brief: > + The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. + examples: ['com.github.pull_request.opened', 'com.example.object.deleted.v2'] + - id: event_subject + type: string + stability: experimental + brief: > + The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). + examples: 'mynewfile.jpg' diff --git a/model/registry/code.yaml b/model/registry/code.yaml new file mode 100644 index 0000000000..967607205a --- /dev/null +++ b/model/registry/code.yaml @@ -0,0 +1,47 @@ +groups: + - id: registry.code + prefix: code + type: attribute_group + brief: > + These attributes allow to report this unit of code and therefore to provide more context about the span. + attributes: + - id: function + type: string + stability: experimental + brief: > + The method or function name, or equivalent (usually rightmost part of the code unit's name). + examples: serveRequest + - id: namespace + type: string + stability: experimental + brief: > + The "namespace" within which `code.function` is defined. Usually the qualified class or module name, + such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. + examples: com.example.MyHttpService + - id: filepath + type: string + stability: experimental + brief: > + The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). + examples: /usr/local/MyApplication/content_root/app/index.php + - id: lineno + type: int + stability: experimental + brief: > + The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. + examples: 42 + - id: column + type: int + stability: experimental + brief: > + The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. + examples: 16 + - id: stacktrace + type: string + stability: experimental + brief: > + A stacktrace as a string in the natural representation for the language runtime. + The representation is to be determined and documented by each language SIG. + examples: 'at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n + at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n + at com.example.GenerateTrace.main(GenerateTrace.java:5)' diff --git a/model/registry/container.yaml b/model/registry/container.yaml new file mode 100644 index 0000000000..b2ff38239f --- /dev/null +++ b/model/registry/container.yaml @@ -0,0 +1,116 @@ +groups: + - id: registry.container + prefix: container + type: attribute_group + brief: > + A container instance. + attributes: + - id: name + type: string + stability: experimental + brief: > + Container name used by container runtime. + examples: ['opentelemetry-autoconf'] + - id: id + type: string + stability: experimental + brief: > + 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. + examples: ['a3bf90e006b2'] + - id: runtime + type: string + stability: experimental + brief: > + The container runtime managing this container. + examples: ['docker', 'containerd', 'rkt'] + - id: image.name + type: string + stability: experimental + brief: > + Name of the image the container was built on. + examples: ['gcr.io/opentelemetry/operator'] + - id: image.tags + type: string[] + stability: experimental + brief: > + Container image tags. An example can be found in + [Docker Image Inspect](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect). + Should be only the `` section of the full name for example + from `registry.example.com/my-org/my-image:`. + examples: ['v1.27.1', '3.5.7-0'] + - id: image.id + type: string + stability: experimental + brief: > + Runtime specific image identifier. Usually a hash algorithm followed by a UUID. + note: > + Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker + container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) + endpoint. + + K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io + /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`. + + The ID is assigned by the container runtime and can vary in different environments. + Consider using `oci.manifest.digest` if it is important to identify the same + image in different environments/runtimes. + examples: ['sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f'] + - id: image.repo_digests + type: string[] + stability: experimental + brief: > + Repo digests of the container image as provided by the container runtime. + note: > + [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. + examples: + - 'example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb' + - 'internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578' + - id: command + type: string + stability: experimental + note: > + If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. + brief: > + The command used to run the container (i.e. the command name). + examples: [ 'otelcontribcol' ] + - id: command_line + type: string + stability: experimental + brief: > + The full command run by the container as a single string representing the full command. [2] + examples: [ 'otelcontribcol --config config.yaml' ] + - id: command_args + type: string[] + stability: experimental + brief: > + All the command arguments (including the command/executable itself) run by the container. [2] + examples: [ 'otelcontribcol, --config, config.yaml' ] + - id: label + type: template[string] + stability: experimental + 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/db.yaml b/model/registry/db.yaml new file mode 100644 index 0000000000..612a9d2132 --- /dev/null +++ b/model/registry/db.yaml @@ -0,0 +1,487 @@ +groups: + - id: registry.db + prefix: db + type: attribute_group + brief: > + This group defines the attributes used to describe telemetry in the context of databases. + attributes: + - id: collection.name + type: string + stability: experimental + brief: The name of a collection (table, container) within the database. + note: > + If the collection name is parsed from the query, it SHOULD match the value provided + in the query and may be qualified with the schema and database name. + examples: ['public.users', 'customers'] + - id: namespace + type: string + stability: experimental + brief: > + The name of the database, fully qualified within the server address and port. + note: > + If a database system has multiple namespace components, they SHOULD be concatenated + (potentially using database system specific conventions) from most general to most + specific namespace component, and more specific namespaces SHOULD NOT be captured without + the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid. + + Semantic conventions for individual database systems SHOULD document what `db.namespace` + means in the context of that system. + examples: [ 'customers', 'test.users' ] + - id: operation.name + type: string + stability: experimental + brief: > + The name of the operation or command being executed. + examples: ['findAndModify', 'HMSET', 'SELECT'] + - id: query.text + type: string + stability: experimental + brief: > + The database query being executed. + 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. + note: > + 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. + examples: ['someval', '55'] + - id: system + brief: An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. + type: + allow_custom_values: true + members: + - id: other_sql + value: 'other_sql' + brief: 'Some other SQL database. Fallback only. See notes.' + stability: experimental + - id: mssql + value: 'mssql' + brief: 'Microsoft SQL Server' + stability: experimental + - id: mssqlcompact + value: 'mssqlcompact' + brief: 'Microsoft SQL Server Compact' + stability: experimental + - id: mysql + value: 'mysql' + brief: 'MySQL' + stability: experimental + - id: oracle + value: 'oracle' + brief: 'Oracle Database' + stability: experimental + - id: db2 + value: 'db2' + brief: 'IBM Db2' + stability: experimental + - id: postgresql + value: 'postgresql' + brief: 'PostgreSQL' + stability: experimental + - id: redshift + value: 'redshift' + brief: 'Amazon Redshift' + stability: experimental + - id: hive + value: 'hive' + brief: 'Apache Hive' + stability: experimental + - id: cloudscape + value: 'cloudscape' + brief: 'Cloudscape' + stability: experimental + - id: hsqldb + value: 'hsqldb' + brief: 'HyperSQL DataBase' + stability: experimental + - id: progress + value: 'progress' + brief: 'Progress Database' + stability: experimental + - id: maxdb + value: 'maxdb' + brief: 'SAP MaxDB' + stability: experimental + - id: hanadb + value: 'hanadb' + brief: 'SAP HANA' + stability: experimental + - id: ingres + value: 'ingres' + brief: 'Ingres' + stability: experimental + - id: firstsql + value: 'firstsql' + brief: 'FirstSQL' + stability: experimental + - id: edb + value: 'edb' + brief: 'EnterpriseDB' + stability: experimental + - id: cache + value: 'cache' + brief: 'InterSystems Caché' + stability: experimental + - id: adabas + value: 'adabas' + brief: 'Adabas (Adaptable Database System)' + stability: experimental + - id: firebird + value: 'firebird' + brief: 'Firebird' + stability: experimental + - id: derby + value: 'derby' + brief: 'Apache Derby' + stability: experimental + - id: filemaker + value: 'filemaker' + brief: 'FileMaker' + stability: experimental + - id: informix + value: 'informix' + brief: 'Informix' + stability: experimental + - id: instantdb + value: 'instantdb' + brief: 'InstantDB' + stability: experimental + - id: interbase + value: 'interbase' + brief: 'InterBase' + stability: experimental + - id: mariadb + value: 'mariadb' + brief: 'MariaDB' + stability: experimental + - id: netezza + value: 'netezza' + brief: 'Netezza' + stability: experimental + - id: pervasive + value: 'pervasive' + brief: 'Pervasive PSQL' + stability: experimental + - id: pointbase + value: 'pointbase' + brief: 'PointBase' + stability: experimental + - id: sqlite + value: 'sqlite' + brief: 'SQLite' + stability: experimental + - id: sybase + value: 'sybase' + brief: 'Sybase' + stability: experimental + - id: teradata + value: 'teradata' + brief: 'Teradata' + stability: experimental + - id: vertica + value: 'vertica' + brief: 'Vertica' + stability: experimental + - id: h2 + value: 'h2' + brief: 'H2' + stability: experimental + - id: coldfusion + value: 'coldfusion' + brief: 'ColdFusion IMQ' + stability: experimental + - id: cassandra + value: 'cassandra' + brief: 'Apache Cassandra' + stability: experimental + - id: hbase + value: 'hbase' + brief: 'Apache HBase' + stability: experimental + - id: mongodb + value: 'mongodb' + brief: 'MongoDB' + stability: experimental + - id: redis + value: 'redis' + brief: 'Redis' + stability: experimental + - id: couchbase + value: 'couchbase' + brief: 'Couchbase' + stability: experimental + - id: couchdb + value: 'couchdb' + brief: 'CouchDB' + stability: experimental + - id: cosmosdb + value: 'cosmosdb' + brief: 'Microsoft Azure Cosmos DB' + stability: experimental + - id: dynamodb + value: 'dynamodb' + brief: 'Amazon DynamoDB' + stability: experimental + - id: neo4j + value: 'neo4j' + brief: 'Neo4j' + stability: experimental + - id: geode + value: 'geode' + brief: 'Apache Geode' + stability: experimental + - id: elasticsearch + value: 'elasticsearch' + brief: 'Elasticsearch' + stability: experimental + - id: memcached + value: 'memcached' + brief: 'Memcached' + stability: experimental + - id: cockroachdb + value: 'cockroachdb' + brief: 'CockroachDB' + stability: experimental + - id: opensearch + value: 'opensearch' + brief: 'OpenSearch' + stability: experimental + - id: clickhouse + value: 'clickhouse' + brief: 'ClickHouse' + stability: experimental + - id: spanner + value: 'spanner' + brief: 'Cloud Spanner' + stability: experimental + - id: trino + value: 'trino' + brief: 'Trino' + stability: experimental + stability: experimental + - id: client.connections.state + stability: experimental + type: + allow_custom_values: true + members: + - id: idle + value: 'idle' + stability: experimental + - id: used + value: 'used' + stability: experimental + brief: "The state of a connection in the pool" + examples: ["idle"] + - id: client.connections.pool.name + type: string + stability: experimental + brief: > + 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`. + examples: ["myDataSource"] + - id: registry.db.cassandra + prefix: db + type: attribute_group + brief: > + This group defines attributes for Cassandra. + attributes: + - id: cassandra.coordinator.dc + type: string + stability: experimental + brief: > + The data center of the coordinating node for a query. + examples: 'us-west-2' + - id: cassandra.coordinator.id + type: string + stability: experimental + brief: > + The ID of the coordinating node for a query. + examples: 'be13faa2-8574-4d71-926d-27f16cf8a7af' + - id: cassandra.consistency_level + brief: > + The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). + type: + members: + - id: all + value: 'all' + stability: experimental + - id: each_quorum + value: 'each_quorum' + stability: experimental + - id: quorum + value: 'quorum' + stability: experimental + - id: local_quorum + value: 'local_quorum' + stability: experimental + - id: one + value: 'one' + stability: experimental + - id: two + value: 'two' + stability: experimental + - id: three + value: 'three' + stability: experimental + - id: local_one + value: 'local_one' + stability: experimental + - id: any + value: 'any' + stability: experimental + - id: serial + value: 'serial' + stability: experimental + - id: local_serial + value: 'local_serial' + stability: experimental + stability: experimental + - id: cassandra.idempotence + type: boolean + stability: experimental + brief: > + Whether or not the query is idempotent. + - id: cassandra.page_size + type: int + stability: experimental + brief: > + The fetch size used for paging, i.e. how many rows will be returned at once. + examples: [5000] + - id: cassandra.speculative_execution_count + type: int + stability: experimental + brief: > + The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. + examples: [0, 2] + - id: registry.db.cosmosdb + prefix: db + type: attribute_group + brief: > + This group defines attributes for Azure Cosmos DB. + attributes: + - id: cosmosdb.client_id + type: string + stability: experimental + brief: Unique Cosmos client instance id. + examples: '3ba4827d-4422-483f-b59f-85b74211c11d' + - id: cosmosdb.connection_mode + type: + allow_custom_values: false + members: + - id: gateway + value: 'gateway' + brief: Gateway (HTTP) connections mode + stability: experimental + - id: direct + value: 'direct' + brief: Direct connection. + stability: experimental + stability: experimental + brief: Cosmos client connection mode. + - id: cosmosdb.operation_type + type: + allow_custom_values: true + members: + - id: invalid + value: 'Invalid' + stability: experimental + - id: create + value: 'Create' + stability: experimental + - id: patch + value: 'Patch' + stability: experimental + - id: read + value: 'Read' + stability: experimental + - id: read_feed + value: 'ReadFeed' + stability: experimental + - id: delete + value: 'Delete' + stability: experimental + - id: replace + value: 'Replace' + stability: experimental + - id: execute + value: 'Execute' + stability: experimental + - id: query + value: 'Query' + stability: experimental + - id: head + value: 'Head' + stability: experimental + - id: head_feed + value: 'HeadFeed' + stability: experimental + - id: upsert + value: 'Upsert' + stability: experimental + - id: batch + value: 'Batch' + stability: experimental + - id: query_plan + value: 'QueryPlan' + stability: experimental + - id: execute_javascript + value: 'ExecuteJavaScript' + stability: experimental + stability: experimental + brief: CosmosDB Operation Type. + - id: cosmosdb.request_charge + type: double + stability: experimental + brief: RU consumed for that operation + examples: [46.18, 1.0] + - id: cosmosdb.request_content_length + type: int + stability: experimental + brief: Request payload size in bytes + - id: cosmosdb.status_code + type: int + stability: experimental + brief: Cosmos DB status code. + examples: [200, 201] + - id: cosmosdb.sub_status_code + type: int + stability: experimental + brief: Cosmos DB sub status code. + examples: [1000, 1002] + - id: registry.db.elasticsearch + prefix: db + type: attribute_group + 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 + brief: > + Represents the human-readable identifier of the node/instance to which a request was routed. + examples: ["instance-0000000001"] + - id: elasticsearch.path_parts + type: template[string] + stability: experimental + brief: > + A dynamic value in the url path. + note: > + Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format + `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD + reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) + in order to map the path part values to their names. + examples: ['db.elasticsearch.path_parts.index=test-index', 'db.elasticsearch.path_parts.doc_id=123'] diff --git a/model/registry/deployment.yaml b/model/registry/deployment.yaml new file mode 100644 index 0000000000..ffc0050eab --- /dev/null +++ b/model/registry/deployment.yaml @@ -0,0 +1,22 @@ +groups: + - id: registry.deployment + prefix: deployment + type: attribute_group + brief: > + This document defines attributes for software deployments. + attributes: + - id: environment + type: string + stability: experimental + brief: > + Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) + (aka deployment tier). + note: | + `deployment.environment` does not affect the uniqueness constraints defined through + the `service.namespace`, `service.name` and `service.instance.id` resource attributes. + This implies that resources carrying the following attribute combinations MUST be + considered to be identifying the same service: + + * `service.name=frontend`, `deployment.environment=production` + * `service.name=frontend`, `deployment.environment=staging`. + examples: ['staging', 'production'] diff --git a/model/registry/deprecated/android.yaml b/model/registry/deprecated/android.yaml new file mode 100644 index 0000000000..97e9bd1e7a --- /dev/null +++ b/model/registry/deprecated/android.yaml @@ -0,0 +1,36 @@ +groups: + - id: registry.android.deprecated + prefix: android + type: attribute_group + brief: > + This document defines attributes that represents an occurrence of a lifecycle transition on the Android platform. + attributes: + - id: state + stability: experimental + brief: > + Deprecated use the `device.app.lifecycle` event definition including + `android.state` as a payload field instead. + note: > + The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), + and from which the `OS identifiers` are derived. + type: + allow_custom_values: true + members: + - id: created + value: 'created' + brief: > + Any time before Activity.onResume() or, if the app has no Activity, Context.startService() + has been called in the app for the first time. + stability: experimental + - id: background + value: 'background' + brief: > + Any time after Activity.onPause() or, if the app has no Activity, + Context.stopService() has been called when the app was in the foreground state. + stability: experimental + - id: foreground + value: 'foreground' + brief: > + Any time after Activity.onResume() or, if the app has no Activity, + Context.startService() has been called when the app was in either the created or background states. + stability: experimental diff --git a/model/registry/deprecated/container.yaml b/model/registry/deprecated/container.yaml new file mode 100644 index 0000000000..77f3466f02 --- /dev/null +++ b/model/registry/deprecated/container.yaml @@ -0,0 +1,11 @@ +groups: + - id: registry.container.deprecated + type: attribute_group + brief: "Describes deprecated container attributes." + attributes: + - id: container.labels + type: template[string] + examples: [ 'container.label.app=nginx' ] + brief: "Deprecated, use `container.label` instead." + stability: experimental + deprecated: "Replaced by `container.label`." diff --git a/model/registry/deprecated/db.yaml b/model/registry/deprecated/db.yaml new file mode 100644 index 0000000000..8e24430d20 --- /dev/null +++ b/model/registry/deprecated/db.yaml @@ -0,0 +1,112 @@ +groups: + - id: registry.db.deprecated + prefix: db + type: attribute_group + brief: > + "Describes deprecated db attributes." + attributes: + - id: connection_string + type: string + brief: 'Deprecated, use `server.address`, `server.port` attributes instead.' + stability: experimental + deprecated: > + "Replaced by `server.address` and `server.port`." + examples: Server=(localdb)\v11.0;Integrated Security=true; + - id: jdbc.driver_classname + type: string + brief: 'Removed, no replacement at this time.' + stability: experimental + deprecated: 'Removed as not used.' + examples: ['org.postgresql.Driver', 'com.microsoft.sqlserver.jdbc.SQLServerDriver'] + - id: operation + type: string + brief: 'Deprecated, use `db.operation.name` instead.' + stability: experimental + deprecated: "Replaced by `db.operation.name`." + examples: ['findAndModify', 'HMSET', 'SELECT'] + - id: user + type: string + brief: 'Deprecated, no replacement at this time.' + deprecated: "No replacement at this time." + stability: experimental + examples: ['readonly_user', 'reporting_user'] + - id: statement + type: string + brief: The database statement being executed. + deprecated: "Replaced by `db.query.text`." + stability: experimental + examples: ['SELECT * FROM wuser_table', 'SET mykey "WuValue"'] + - id: cassandra.table + type: string + stability: experimental + brief: 'Deprecated, use `db.collection.name` instead.' + deprecated: "Replaced by `db.collection.name`." + examples: 'mytable' + - id: cosmosdb.container + type: string + stability: experimental + brief: 'Deprecated, use `db.collection.name` instead.' + deprecated: "Replaced by `db.collection.name`." + examples: 'mytable' + - id: mongodb.collection + type: string + stability: experimental + brief: 'Deprecated, use `db.collection.name` instead.' + deprecated: "Replaced by `db.collection.name`." + examples: 'mytable' + - id: sql.table + type: string + stability: experimental + brief: 'Deprecated, use `db.collection.name` instead.' + deprecated: "Replaced by `db.collection.name`." + examples: 'mytable' + - id: redis.database_index + type: int + stability: experimental + brief: 'Deprecated, use `db.namespace` instead.' + deprecated: "Replaced by `db.namespace`." + examples: [0, 1, 15] + - id: name + type: string + stability: experimental + brief: 'Deprecated, use `db.namespace` instead.' + deprecated: "Replaced by `db.namespace`." + examples: [ 'customers', 'main' ] + - id: mssql.instance_name + type: string + stability: experimental + brief: 'Deprecated, SQL Server instance is now populated as a part of `db.namespace` attribute.' + deprecated: 'Deprecated, no replacement at this time.' + examples: 'MSSQLSERVER' + - id: instance.id + type: string + stability: experimental + 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: registry.db.metrics.deprecated + type: attribute_group + brief: > + "Describes deprecated db metrics attributes." + attributes: + - id: 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.connections.state` instead." + deprecated: "Replaced by `db.client.connections.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`." + examples: ["myDataSource"] diff --git a/model/registry/deprecated/http.yaml b/model/registry/deprecated/http.yaml new file mode 100644 index 0000000000..4eaaa6ce19 --- /dev/null +++ b/model/registry/deprecated/http.yaml @@ -0,0 +1,86 @@ +groups: + - id: registry.http.deprecated + type: attribute_group + brief: "Describes deprecated HTTP attributes." + prefix: http + attributes: + - id: method + type: string + brief: 'Deprecated, use `http.request.method` instead.' + stability: experimental + deprecated: "Replaced by `http.request.method`." + examples: ["GET", "POST", "HEAD"] + - id: status_code + type: int + brief: 'Deprecated, use `http.response.status_code` instead.' + stability: experimental + deprecated: "Replaced by `http.response.status_code`." + examples: [200] + - id: scheme + type: string + brief: 'Deprecated, use `url.scheme` instead.' + stability: experimental + deprecated: "Replaced by `url.scheme` instead." + examples: ['http', 'https'] + - id: url + type: string + brief: 'Deprecated, use `url.full` instead.' + stability: experimental + deprecated: "Replaced by `url.full`." + examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv'] + - id: target + type: string + brief: 'Deprecated, use `url.path` and `url.query` instead.' + stability: experimental + deprecated: "Split to `url.path` and `url.query." + examples: ['/search?q=OpenTelemetry#SemConv'] + - id: request_content_length + type: int + brief: 'Deprecated, use `http.request.header.content-length` instead.' + stability: experimental + deprecated: "Replaced by `http.request.header.content-length`." + examples: 3495 + - id: response_content_length + type: int + brief: 'Deprecated, use `http.response.header.content-length` instead.' + stability: experimental + deprecated: "Replaced by `http.response.header.content-length`." + examples: 3495 + - id: flavor + type: + allow_custom_values: true + members: + - id: http_1_0 + value: '1.0' + brief: 'HTTP/1.0' + stability: experimental + - id: http_1_1 + value: '1.1' + brief: 'HTTP/1.1' + stability: experimental + - id: http_2_0 + value: '2.0' + brief: 'HTTP/2' + stability: experimental + - id: http_3_0 + value: '3.0' + brief: 'HTTP/3' + stability: experimental + - id: spdy + value: 'SPDY' + brief: 'SPDY protocol.' + stability: experimental + - id: quic + value: 'QUIC' + brief: 'QUIC protocol.' + stability: experimental + brief: 'Deprecated, use `network.protocol.name` instead.' + deprecated: "Replaced by `network.protocol.name`." + stability: experimental + - id: user_agent + type: string + brief: 'Deprecated, use `user_agent.original` instead.' + examples: ['CERN-LineMode/2.15 libwww/2.17b3', + 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1'] + deprecated: "Replaced by `user_agent.original`." + stability: experimental diff --git a/model/registry/deprecated/ios.yaml b/model/registry/deprecated/ios.yaml new file mode 100644 index 0000000000..acc1a9f1f9 --- /dev/null +++ b/model/registry/deprecated/ios.yaml @@ -0,0 +1,46 @@ +groups: + - id: registry.ios.deprecated + prefix: ios + type: attribute_group + brief: > + The iOS platform on which the iOS application is running. + attributes: + - id: state + stability: experimental + deprecated: "Moved to a payload field of `device.app.lifecycle`." + note: > + The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), + and from which the `OS terminology` column values are derived. + brief: > + Deprecated use the `device.app.lifecycle` event definition including + `ios.state` as a payload field instead. + type: + allow_custom_values: true + members: + - id: active + value: 'active' + brief: > + The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. + stability: experimental + - id: inactive + value: 'inactive' + brief: > + The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. + stability: experimental + - id: background + value: 'background' + brief: > + The app is now in the background. + This value is associated with UIKit notification `applicationDidEnterBackground`. + stability: experimental + - id: foreground + value: 'foreground' + brief: > + The app is now in the foreground. + This value is associated with UIKit notification `applicationWillEnterForeground`. + stability: experimental + - id: terminate + value: 'terminate' + brief: > + The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. + stability: experimental diff --git a/model/registry/deprecated/k8s.yaml b/model/registry/deprecated/k8s.yaml new file mode 100644 index 0000000000..e2785dd08e --- /dev/null +++ b/model/registry/deprecated/k8s.yaml @@ -0,0 +1,11 @@ +groups: + - id: registry.k8s.deprecated + type: attribute_group + brief: "Describes deprecated k8s attributes." + attributes: + - id: k8s.pod.labels + type: template[string] + examples: ['k8s.pod.label.app=my-app'] + brief: "Deprecated, use `k8s.pod.label` instead." + stability: experimental + deprecated: "Replaced by `k8s.pod.label`." diff --git a/model/registry/deprecated/messaging.yaml b/model/registry/deprecated/messaging.yaml new file mode 100644 index 0000000000..4f27d8e09a --- /dev/null +++ b/model/registry/deprecated/messaging.yaml @@ -0,0 +1,19 @@ +groups: + - id: registry.messaging.deprecated + type: attribute_group + brief: "Describes deprecated messaging attributes." + attributes: + - id: messaging.kafka.destination.partition + type: int + brief: > + Deprecated, use `messaging.destination.partition.id` instead. + examples: 2 + deprecated: "Replaced by `messaging.destination.partition.id`." + stability: experimental + - id: messaging.operation + type: string + stability: experimental + brief: > + Deprecated, use `messaging.operation.type` instead. + examples: ["publish", "create", "process"] + deprecated: "Replaced by `messaging.operation.type`." diff --git a/model/deprecated/network.yaml b/model/registry/deprecated/network.yaml similarity index 59% rename from model/deprecated/network.yaml rename to model/registry/deprecated/network.yaml index 17b75b90e3..6614467174 100644 --- a/model/deprecated/network.yaml +++ b/model/registry/deprecated/network.yaml @@ -1,5 +1,5 @@ groups: - - id: network-deprecated + - id: registry.network.deprecated prefix: net type: attribute_group brief: > @@ -7,49 +7,57 @@ groups: attributes: - id: sock.peer.name type: string - stability: deprecated - brief: Deprecated, use `server.socket.domain` on client spans. + deprecated: "Removed." + stability: experimental + brief: Deprecated, no replacement at this time. examples: ['/var/my.sock'] - id: sock.peer.addr type: string - stability: deprecated - brief: > - Deprecated, use `server.socket.address` on client spans and `client.socket.address` on server spans. + deprecated: "Replaced by `network.peer.address`." + stability: experimental + brief: Deprecated, use `network.peer.address`. examples: ['192.168.0.1'] - id: sock.peer.port type: int - stability: deprecated + deprecated: "Replaced by `network.peer.port`." + stability: experimental examples: [65531] - brief: Deprecated, use `server.socket.port` on client spans and `client.socket.port` on server spans. + brief: Deprecated, use `network.peer.port`. - id: peer.name type: string - stability: deprecated + deprecated: "Replaced by `server.address` on client spans and `client.address` on server spans." + stability: experimental brief: Deprecated, use `server.address` on client spans and `client.address` on server spans. examples: ['example.com'] - id: peer.port type: int - stability: deprecated + deprecated: "Replaced by `server.port` on client spans and `client.port` on server spans." + stability: experimental brief: Deprecated, use `server.port` on client spans and `client.port` on server spans. examples: [8080] - id: host.name type: string - stability: deprecated + deprecated: "Replaced by `server.address`." + stability: experimental brief: Deprecated, use `server.address`. examples: ['example.com'] - id: host.port type: int - stability: deprecated + deprecated: "Replaced by `server.port`." + stability: experimental brief: Deprecated, use `server.port`. examples: [8080] - id: sock.host.addr type: string - stability: deprecated - brief: Deprecated, use `server.socket.address`. + deprecated: "Replaced by `network.local.address`." + stability: experimental + brief: Deprecated, use `network.local.address`. examples: ['/var/my.sock'] - id: sock.host.port type: int - stability: deprecated - brief: Deprecated, use `server.socket.port`. + deprecated: "Replaced by `network.local.port`." + stability: experimental + brief: Deprecated, use `network.local.port`. examples: [8080] - id: transport type: @@ -57,31 +65,39 @@ groups: members: - id: ip_tcp value: "ip_tcp" + stability: experimental - id: ip_udp value: "ip_udp" + stability: experimental - id: pipe value: "pipe" brief: 'Named or anonymous pipe.' + stability: experimental - id: inproc value: "inproc" brief: 'In-process communication.' + stability: experimental note: > Signals that there is only in-process communication not using a "real" network protocol in cases where network attributes would normally be expected. Usually all other network attributes can be left out in that case. - id: other value: "other" + stability: experimental brief: 'Something else (non IP-based).' - stability: deprecated + deprecated: "Replaced by `network.transport`." + stability: experimental brief: Deprecated, use `network.transport`. - id: protocol.name type: string - stability: deprecated + deprecated: "Replaced by `network.protocol.name`." + stability: experimental brief: Deprecated, use `network.protocol.name`. examples: ['amqp', 'http', 'mqtt'] - id: protocol.version type: string - stability: deprecated + deprecated: "Replaced by `network.protocol.version`." + stability: experimental brief: Deprecated, use `network.protocol.version`. examples: '3.1.1' - id: sock.family @@ -91,11 +107,15 @@ groups: - id: inet value: 'inet' brief: "IPv4 address" + stability: experimental - id: inet6 value: 'inet6' brief: "IPv6 address" + stability: experimental - id: unix value: 'unix' brief: "Unix domain socket path" - stability: deprecated + stability: experimental + deprecated: "Split to `network.transport` and `network.type`." + stability: experimental brief: Deprecated, use `network.transport` and `network.type`. diff --git a/model/registry/deprecated/otel.yaml b/model/registry/deprecated/otel.yaml new file mode 100644 index 0000000000..c52a51fe8c --- /dev/null +++ b/model/registry/deprecated/otel.yaml @@ -0,0 +1,18 @@ +groups: + - id: registry.otel.library.deprecated + prefix: otel.library + type: attribute_group + brief: "Describes deprecated otel.library attributes." + attributes: + - id: name + type: string + deprecated: use the `otel.scope.name` attribute. + stability: experimental + brief: + examples: ['io.opentelemetry.contrib.mongodb'] + - id: version + type: string + deprecated: use the `otel.scope.version` attribute. + stability: experimental + brief: + examples: ['1.0.0'] diff --git a/model/registry/deprecated/rpc.yaml b/model/registry/deprecated/rpc.yaml new file mode 100644 index 0000000000..1d9d22c2d4 --- /dev/null +++ b/model/registry/deprecated/rpc.yaml @@ -0,0 +1,32 @@ +groups: + - id: registry.rpc.deprecated + type: attribute_group + brief: 'Deprecated rpc message attributes.' + attributes: + - id: message.type + type: + members: + - id: sent + value: "SENT" + stability: experimental + - id: received + value: "RECEIVED" + stability: experimental + stability: experimental + brief: "Deprecated, use `rpc.message.type` instead." + deprecated: "Replaced by `rpc.message.type`." + - id: message.id + type: int + stability: experimental + brief: "Deprecated, use `rpc.message.id` instead." + deprecated: "Replaced by `rpc.message.id`." + - id: message.compressed_size + type: int + stability: experimental + brief: "Deprecated, use `rpc.message.compressed_size` instead." + deprecated: "Replaced by `rpc.message.compressed_size`." + - id: message.uncompressed_size + type: int + stability: experimental + brief: "Deprecated, use `rpc.message.uncompressed_size` instead." + deprecated: "Replaced by `rpc.message.uncompressed_size`." diff --git a/model/registry/deprecated/system.yaml b/model/registry/deprecated/system.yaml new file mode 100644 index 0000000000..700023ab57 --- /dev/null +++ b/model/registry/deprecated/system.yaml @@ -0,0 +1,25 @@ +groups: + - id: registry.system.deprecated + type: attribute_group + brief: "Deprecated system attributes." + attributes: + - id: system.processes.status + type: + allow_custom_values: true + members: + - id: running + value: 'running' + stability: experimental + - id: sleeping + value: 'sleeping' + stability: experimental + - id: stopped + value: 'stopped' + stability: experimental + - id: defunct + value: 'defunct' + stability: experimental + brief: "Deprecated, use `system.process.status` instead." + deprecated: "Replaced by `system.process.status`." + stability: experimental + examples: ["running"] diff --git a/model/registry/destination.yaml b/model/registry/destination.yaml new file mode 100644 index 0000000000..c05a0c992a --- /dev/null +++ b/model/registry/destination.yaml @@ -0,0 +1,25 @@ +groups: + - id: registry.destination + prefix: destination + type: attribute_group + brief: > + These attributes may be used to describe the receiver of a network exchange/packet. These should be used + when there is no client/server relationship between the two sides, or when that relationship is unknown. + This covers low-level network interactions (e.g. packet tracing) where you don't know if + there was a connection or which side initiated it. + This also covers unidirectional UDP flows and peer-to-peer communication where the + "user-facing" surface of the protocol / API doesn't expose a clear notion of client and server. + attributes: + - id: address + type: string + stability: experimental + brief: "Destination address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name." + note: > + When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent + the destination address behind any intermediaries, for example proxies, if it's available. + examples: ['destination.example.com', '10.1.2.80', '/tmp/my.sock'] + - id: port + type: int + stability: experimental + brief: 'Destination port number' + examples: [3389, 2888] diff --git a/model/registry/device.yaml b/model/registry/device.yaml new file mode 100644 index 0000000000..5c324e37fe --- /dev/null +++ b/model/registry/device.yaml @@ -0,0 +1,50 @@ +groups: + - id: registry.device + prefix: device + type: attribute_group + brief: > + Describes device attributes. + attributes: + - id: id + type: string + stability: experimental + brief: > + A unique identifier representing the device + note: > + The device identifier MUST only be defined using the values outlined below. This value is not an advertising + identifier and MUST NOT be used as such. + On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). + On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique + UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) + on best practices and exact implementation details. + Caution should be taken when storing personal data or anything which can identify a user. GDPR and + data protection laws may apply, ensure you do your own due diligence. + examples: ['2ab2916d-a51f-4ac8-80ee-45ac31a28092'] + - id: manufacturer + type: string + stability: experimental + brief: > + The name of the device manufacturer + note: > + The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). + iOS apps SHOULD hardcode the value `Apple`. + examples: ['Apple', 'Samsung'] + - id: model.identifier + type: string + stability: experimental + brief: > + The model identifier for the device + note: > + It's recommended this value represents a machine-readable version of + the model identifier rather than the market or consumer-friendly name + of the device. + examples: ['iPhone3,4', 'SM-G920F'] + - id: model.name + type: string + stability: experimental + brief: > + The marketing name for the device model + note: > + It's recommended this value represents a human-readable version of the + device model rather than a machine-readable alternative. + examples: ['iPhone 6s Plus', 'Samsung Galaxy S6'] diff --git a/model/registry/disk.yaml b/model/registry/disk.yaml new file mode 100644 index 0000000000..aa8c091135 --- /dev/null +++ b/model/registry/disk.yaml @@ -0,0 +1,20 @@ +groups: + - id: registry.disk + prefix: disk + type: attribute_group + brief: > + These attributes may be used for any disk related operation. + attributes: + - id: io.direction + type: + allow_custom_values: false + members: + - id: read + value: 'read' + stability: experimental + - id: write + value: 'write' + stability: experimental + stability: experimental + brief: "The disk IO operation direction." + examples: ["read"] diff --git a/model/registry/dns.yaml b/model/registry/dns.yaml new file mode 100644 index 0000000000..d4042c4add --- /dev/null +++ b/model/registry/dns.yaml @@ -0,0 +1,18 @@ +groups: + - id: registry.dns + type: attribute_group + prefix: dns + brief: > + This document defines the shared attributes used to report a DNS query. + attributes: + - id: question.name + type: string + stability: experimental + brief: The name being queried. + examples: ["www.example.com", "opentelemetry.io"] + note: > + If the name field contains non-printable + characters (below 32 or above 126), those characters should be represented + as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. + Tabs, carriage returns, and line feeds should be converted to \t, \r, and + \n respectively. diff --git a/model/registry/enduser.yaml b/model/registry/enduser.yaml new file mode 100644 index 0000000000..656f36d682 --- /dev/null +++ b/model/registry/enduser.yaml @@ -0,0 +1,29 @@ +groups: + - id: registry.enduser + prefix: enduser + type: attribute_group + brief: > + This document defines attributes for operations with an authenticated and/or authorized enduser. + attributes: + - id: id + type: string + stability: experimental + brief: > + Username or client_id extracted from the access token or + [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) + header in the inbound request from outside the system. + examples: 'username' + - id: role + type: string + stability: experimental + brief: 'Actual/assumed role the client is making the request under extracted from token or application security context.' + examples: 'admin' + - id: scope + type: string + stability: experimental + brief: > + Scopes or granted authorities the client currently possesses extracted from token + or application security context. The value would come from the scope associated + with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3) + or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). + examples: 'read:message, write:files' diff --git a/model/registry/error.yaml b/model/registry/error.yaml new file mode 100644 index 0000000000..68bde170ba --- /dev/null +++ b/model/registry/error.yaml @@ -0,0 +1,40 @@ +groups: + - id: registry.error + type: attribute_group + prefix: error + brief: > + This document defines the shared attributes used to report an error. + attributes: + - id: type + stability: stable + brief: > + Describes a class of error the operation ended with. + type: + allow_custom_values: true + members: + - id: other + value: "_OTHER" + stability: stable + brief: > + A fallback error value to be used when the instrumentation doesn't define a custom value. + examples: ['timeout', 'java.net.UnknownHostException', 'server_certificate_invalid', '500'] + note: | + 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. diff --git a/model/registry/event.yaml b/model/registry/event.yaml new file mode 100644 index 0000000000..aa69709b69 --- /dev/null +++ b/model/registry/event.yaml @@ -0,0 +1,18 @@ +groups: + - id: registry.event + prefix: event + type: attribute_group + brief: > + Attributes for Events represented using Log Records. + attributes: + - id: name + type: string + stability: experimental + brief: > + Identifies the class / type of event. + note: > + Event names are subject to the same rules as [attribute names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/common/attribute-naming.md). + Notably, event names are namespaced to avoid collisions and provide a clean + separation of semantics for events in separate domains like browser, mobile, and + kubernetes. + examples: ['browser.mouse.click', 'device.app.lifecycle'] diff --git a/model/registry/exception.yaml b/model/registry/exception.yaml new file mode 100644 index 0000000000..70dea3d509 --- /dev/null +++ b/model/registry/exception.yaml @@ -0,0 +1,54 @@ +groups: + - id: registry.exception + type: attribute_group + prefix: exception + brief: > + This document defines the shared attributes used to + report a single exception associated with a span or log. + attributes: + - id: type + type: string + stability: stable + brief: > + The type of the exception (its fully-qualified class name, if applicable). + The dynamic type of the exception should be preferred over the static type + in languages that support it. + examples: ["java.net.ConnectException", "OSError"] + - id: message + type: string + stability: stable + brief: The exception message. + examples: ["Division by zero", "Can't convert 'int' object to str implicitly"] + - id: stacktrace + type: string + stability: stable + brief: > + A stacktrace as a string in the natural representation for the language runtime. + The representation is to be determined and documented by each language SIG. + examples: 'Exception in thread "main" java.lang.RuntimeException: Test exception\n + at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n + at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n + at com.example.GenerateTrace.main(GenerateTrace.java:5)' + - id: escaped + type: boolean + stability: stable + brief: > + SHOULD be set to true if the exception event is recorded at a point where + it is known that the exception is escaping the scope of the span. + note: |- + An exception is considered to have escaped (or left) the scope of a span, + if that span is ended while the exception is still logically "in flight". + This may be actually "in flight" in some languages (e.g. if the exception + is passed to a Context manager's `__exit__` method in Python) but will + usually be caught at the point of recording the exception in most languages. + + It is usually not possible to determine at the point where an exception is thrown + whether it will escape the scope of a span. + However, it is trivial to know that an exception + will escape, if one checks for an active exception just before ending the span, + as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). + + It follows that an exception may still escape the scope of the span + even if the `exception.escaped` attribute was not set or set to false, + since the event might have been recorded at a time where it was not + clear whether the exception will escape. diff --git a/model/registry/faas.yaml b/model/registry/faas.yaml new file mode 100644 index 0000000000..a4fc8a3d55 --- /dev/null +++ b/model/registry/faas.yaml @@ -0,0 +1,208 @@ +groups: + - id: registry.faas + brief: FaaS attributes + type: attribute_group + prefix: faas + attributes: + - id: name + type: string + stability: experimental + brief: > + The name of the single function that this runtime instance executes. + note: | + This is the name of the function as configured/deployed on the FaaS + platform and is usually different from the name of the callback + function (which may be stored in the + [`code.namespace`/`code.function`](/docs/general/attributes.md#source-code-attributes) + span attributes). + + For some cloud providers, the above definition is ambiguous. The following + definition of function name MUST be used for this attribute + (and consequently the span name) for the listed cloud providers/products: + + * **Azure:** The full name `/`, i.e., function app name + followed by a forward slash followed by the function name (this form + can also be seen in the resource JSON for the function). + This means that a span attribute MUST be used, as an Azure function + app can host multiple functions that would usually share + a TracerProvider (see also the `cloud.resource_id` attribute). + examples: ['my-function', 'myazurefunctionapp/some-function-name'] + - id: version + type: string + stability: experimental + brief: The immutable version of the function being executed. + note: | + Depending on the cloud provider and platform, use: + + * **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) + (an integer represented as a decimal string). + * **Google Cloud Run (Services):** The [revision](https://cloud.google.com/run/docs/managing/revisions) + (i.e., the function name plus the revision suffix). + * **Google Cloud Functions:** The value of the + [`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically). + * **Azure Functions:** Not applicable. Do not set this attribute. + examples: ['26', 'pinkfroid-00002'] + - id: instance + type: string + stability: experimental + brief: > + The execution environment ID as a string, that will be potentially reused + for other invocations to the same function/function version. + note: > + * **AWS Lambda:** Use the (full) log stream name. + examples: ['2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de'] + - id: max_memory + type: int + stability: experimental + brief: > + The amount of memory available to the serverless function converted to Bytes. + note: > + It's recommended to set this attribute since e.g. too little memory can easily + stop a Java AWS Lambda function from working correctly. + On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` + provides this information (which must be multiplied by 1,048,576). + examples: 134217728 + - id: trigger + stability: experimental + brief: > + Type of the trigger which caused this function invocation. + type: + allow_custom_values: false + members: + - id: datasource + value: 'datasource' + brief: 'A response to some data source operation such as a database or filesystem read/write' + stability: experimental + - id: http + value: 'http' + brief: 'To provide an answer to an inbound HTTP request' + stability: experimental + - id: pubsub + value: 'pubsub' + brief: 'A function is set to be executed when messages are sent to a messaging system' + stability: experimental + - id: timer + value: 'timer' + brief: 'A function is scheduled to be executed regularly' + stability: experimental + - id: other + value: 'other' + brief: 'If none of the others apply' + stability: experimental + - id: invoked_name + type: string + stability: experimental + brief: > + The name of the invoked function. + note: > + SHOULD be equal to the `faas.name` resource attribute of the + invoked function. + examples: 'my-function' + - id: invoked_provider + stability: experimental + type: + allow_custom_values: true + members: + - id: 'alibaba_cloud' + value: 'alibaba_cloud' + brief: 'Alibaba Cloud' + stability: experimental + - id: 'aws' + value: 'aws' + brief: 'Amazon Web Services' + stability: experimental + - id: 'azure' + value: 'azure' + brief: 'Microsoft Azure' + stability: experimental + - id: 'gcp' + value: 'gcp' + brief: 'Google Cloud Platform' + stability: experimental + - id: 'tencent_cloud' + value: 'tencent_cloud' + brief: 'Tencent Cloud' + stability: experimental + brief: > + The cloud provider of the invoked function. + note: > + SHOULD be equal to the `cloud.provider` resource attribute of the + invoked function. + - id: invoked_region + type: string + stability: experimental + brief: > + The cloud region of the invoked function. + note: > + SHOULD be equal to the `cloud.region` resource attribute of the + invoked function. + examples: 'eu-central-1' + - id: invocation_id + type: string + stability: experimental + brief: > + The invocation ID of the current function invocation. + examples: 'af9d5aa4-a685-4c5f-a22b-444f80b3cc28' + - id: time + type: string + stability: experimental + brief: > + A string containing the function invocation time in the + [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) + format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). + examples: "2020-01-23T13:47:06Z" + - id: cron + type: string + stability: experimental + brief: > + A string containing the schedule period as + [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). + examples: "0/5 * * * ? *" + - id: coldstart + type: boolean + stability: experimental + brief: > + A boolean that is true if the serverless function is executed for the + first time (aka cold-start). + - id: document.collection + type: string + stability: experimental + brief: > + The name of the source on which the triggering operation was performed. + For example, in Cloud Storage or S3 corresponds to the bucket name, + and in Cosmos DB to the database name. + examples: ['myBucketName', 'myDbName'] + - id: document.operation + stability: experimental + type: + allow_custom_values: true + members: + - id: insert + value: 'insert' + brief: 'When a new object is created.' + stability: experimental + - id: edit + value: 'edit' + brief: 'When an object is modified.' + stability: experimental + - id: delete + value: 'delete' + brief: 'When an object is deleted.' + stability: experimental + brief: 'Describes the type of the operation that was performed on the data.' + - id: document.time + type: string + stability: experimental + brief: > + A string containing the time when the data was accessed in the + [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) + format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). + examples: "2020-01-23T13:47:06Z" + - id: document.name + type: string + stability: experimental + brief: > + The document name/table subjected to the operation. + For example, in Cloud Storage or S3 is the name of + the file, and in Cosmos DB the table name. + examples: ["myFile.txt", "myTableName"] diff --git a/model/registry/feature-flag.yaml b/model/registry/feature-flag.yaml new file mode 100644 index 0000000000..9de106ffc8 --- /dev/null +++ b/model/registry/feature-flag.yaml @@ -0,0 +1,33 @@ +groups: + - id: registry.feature_flag + prefix: feature_flag + type: attribute_group + brief: > + This document defines attributes for Feature Flags. + attributes: + - id: key + type: string + stability: experimental + brief: The unique identifier of the feature flag. + examples: ["logo-color"] + - id: provider_name + type: string + stability: experimental + brief: The name of the service provider that performs the flag evaluation. + examples: ["Flag Manager"] + - id: variant + type: string + stability: experimental + examples: ["red", "true", "on"] + brief: > + SHOULD be a semantic identifier for a value. If one is unavailable, a + stringified version of the value can be used. + note: |- + A semantic identifier, commonly referred to as a variant, provides a means + for referring to a value without including the value itself. This can + provide additional context for understanding the meaning behind a value. + For example, the variant `red` maybe be used for the value `#c05543`. + + A stringified version of the value can be used in situations where a + semantic identifier is unavailable. String representation of the value + should be determined by the implementer. diff --git a/model/registry/file.yaml b/model/registry/file.yaml new file mode 100644 index 0000000000..bbe0f99fd2 --- /dev/null +++ b/model/registry/file.yaml @@ -0,0 +1,38 @@ +groups: + - id: registry.file + prefix: file + type: attribute_group + brief: "Describes file attributes." + attributes: + - id: directory + type: string + brief: > + Directory where the file is located. It should include the drive letter, when appropriate. + stability: experimental + examples: ['/home/user', 'C:\Program Files\MyApp'] + - id: extension + type: string + brief: > + File extension, excluding the leading dot. + stability: experimental + examples: ['png', 'gz'] + note: > + When the file name has multiple extensions (example.tar.gz), only the last one should + be captured ("gz", not "tar.gz"). + - id: name + type: string + brief: > + Name of the file including the extension, without the directory. + stability: experimental + examples: ['example.png'] + - id: path + type: string + brief: > + Full path to the file, including the file name. It should include the drive letter, when appropriate. + stability: experimental + examples: ['/home/alice/example.png', 'C:\Program Files\MyApp\myapp.exe'] + - id: size + type: int + brief: > + File size in bytes. + stability: experimental diff --git a/model/registry/gcp.yaml b/model/registry/gcp.yaml new file mode 100644 index 0000000000..3b00f7040e --- /dev/null +++ b/model/registry/gcp.yaml @@ -0,0 +1,48 @@ +groups: + - id: registry.gcp.cloud_run + prefix: gcp.cloud_run + type: attribute_group + brief: > + This document defines attributes for Google Cloud Run. + attributes: + - id: job.execution + type: string + stability: experimental + brief: > + The name of the Cloud Run + [execution](https://cloud.google.com/run/docs/managing/job-executions) + being run for the Job, as set by the + [`CLOUD_RUN_EXECUTION`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) + environment variable. + examples: ['job-name-xxxx', 'sample-job-mdw84'] + - id: job.task_index + type: int + stability: experimental + brief: > + The index for a task within an execution as provided by the + [`CLOUD_RUN_TASK_INDEX`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) + environment variable. + examples: [0, 1] + - id: registry.gcp.gce + prefix: gcp.gce + type: attribute_group + brief: > + This document defines attributes for Google Compute Engine (GCE). + attributes: + - id: instance.name + type: string + stability: experimental + brief: > + The instance name of a GCE instance. This is the value + provided by `host.name`, the visible name of the instance in + the Cloud Console UI, and the prefix for the default + hostname of the instance as defined by the [default internal + DNS + name](https://cloud.google.com/compute/docs/internal-dns#instance-fully-qualified-domain-names). + examples: ['instance-1', 'my-vm-name'] + - id: instance.hostname + type: string + stability: experimental + brief: > + The hostname of a GCE instance. This is the full value of the default or [custom hostname](https://cloud.google.com/compute/docs/instances/custom-hostname-vm). + examples: ['my-host1234.example.com', 'sample-vm.us-west1-b.c.my-project.internal'] diff --git a/model/registry/gen-ai.yaml b/model/registry/gen-ai.yaml new file mode 100644 index 0000000000..100523a3b8 --- /dev/null +++ b/model/registry/gen-ai.yaml @@ -0,0 +1,87 @@ +groups: + - id: registry.gen_ai + 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. + attributes: + - id: system + stability: experimental + type: + allow_custom_values: true + members: + - id: openai + stability: experimental + value: "openai" + brief: 'OpenAI' + brief: The name of the LLM foundation model vendor. + 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. + 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. + examples: [100] + tag: llm-generic-request + - id: request.temperature + stability: experimental + type: double + brief: The temperature setting for the LLM 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. + examples: [1.0] + tag: llm-generic-request + - 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. + 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 + stability: experimental + type: int + brief: The number of tokens used in the LLM prompt. + examples: [100] + tag: llm-generic-response + - id: usage.completion_tokens + stability: experimental + type: int + brief: The number of tokens used in the LLM response (completion). + examples: [180] + tag: llm-generic-response + - id: prompt + stability: experimental + type: string + brief: The full prompt sent to an LLM. + 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. + 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 diff --git a/model/registry/graphql.yaml b/model/registry/graphql.yaml new file mode 100644 index 0000000000..460444d891 --- /dev/null +++ b/model/registry/graphql.yaml @@ -0,0 +1,36 @@ +groups: + - id: registry.graphql + prefix: graphql + type: attribute_group + brief: 'This document defines attributes for GraphQL.' + attributes: + - id: operation.name + brief: "The name of the operation being executed." + type: string + stability: experimental + examples: 'findBookById' + - id: operation.type + brief: "The type of the operation being executed." + stability: experimental + type: + allow_custom_values: false + members: + - id: query + value: "query" + brief: "GraphQL query" + stability: experimental + - id: mutation + value: "mutation" + brief: "GraphQL mutation" + stability: experimental + - id: subscription + value: "subscription" + brief: "GraphQL subscription" + stability: experimental + examples: ['query', 'mutation', 'subscription'] + - id: document + brief: "The GraphQL document being executed." + type: string + stability: experimental + note: The value may be sanitized to exclude sensitive information. + examples: 'query findBookById { bookById(id: ?) { name } }' diff --git a/model/registry/heroku.yaml b/model/registry/heroku.yaml new file mode 100644 index 0000000000..d9fe99a731 --- /dev/null +++ b/model/registry/heroku.yaml @@ -0,0 +1,25 @@ +groups: + - id: registry.heroku + prefix: heroku + type: attribute_group + brief: > + This document defines attributes for the Android platform on which the Android application is running. + attributes: + - id: release.creation_timestamp + type: string + stability: experimental + brief: > + Time and date the release was created + examples: [ '2022-10-23T18:00:42Z' ] + - id: release.commit + type: string + stability: experimental + brief: > + Commit hash for the current release + examples: [ 'e6134959463efd8966b20e75b913cafe3f5ec' ] + - id: app.id + type: string + stability: experimental + brief: > + Unique identifier for the application + examples: [ '2daa2797-e42b-4624-9322-ec3f968df4da' ] diff --git a/model/registry/host.yaml b/model/registry/host.yaml new file mode 100644 index 0000000000..332ea01f9c --- /dev/null +++ b/model/registry/host.yaml @@ -0,0 +1,145 @@ +groups: + - id: registry.host + prefix: host + type: attribute_group + brief: > + A host is defined as a computing instance. For example, physical servers, virtual machines, switches or disk array. + attributes: + - id: id + type: string + stability: experimental + brief: > + Unique host ID. For Cloud, this must be the instance_id assigned by the cloud provider. + For non-containerized systems, this should be the `machine-id`. See the table below for + the sources to use to determine the `machine-id` based on operating system. + examples: ['fdbf79e8af94cb7f9e8df36789187052'] + - id: name + type: string + stability: experimental + brief: > + Name of the host. On Unix systems, it may contain what the hostname + command returns, or the fully qualified hostname, or another name + specified by the user. + examples: ['opentelemetry-test'] + - id: type + type: string + stability: experimental + brief: > + Type of host. For Cloud, this must be the machine type. + examples: ['n1-standard-1'] + - id: arch + type: + allow_custom_values: true + members: + - id: amd64 + value: 'amd64' + brief: "AMD64" + stability: experimental + - id: arm32 + value: 'arm32' + brief: "ARM32" + stability: experimental + - id: arm64 + value: 'arm64' + brief: "ARM64" + stability: experimental + - id: ia64 + value: 'ia64' + brief: "Itanium" + stability: experimental + - id: ppc32 + value: 'ppc32' + brief: "32-bit PowerPC" + stability: experimental + - id: ppc64 + value: 'ppc64' + brief: "64-bit PowerPC" + stability: experimental + - id: s390x + value: 's390x' + brief: "IBM z/Architecture" + stability: experimental + - id: x86 + value: 'x86' + brief: "32-bit x86" + stability: experimental + stability: experimental + brief: > + The CPU architecture the host system is running on. + - id: image.name + type: string + stability: experimental + brief: > + Name of the VM image or OS install the host was instantiated from. + examples: ['infra-ami-eks-worker-node-7d4ec78312', 'CentOS-8-x86_64-1905'] + - id: image.id + stability: experimental + type: string + brief: > + VM image ID or host OS image ID. For Cloud, this value is from the provider. + examples: ['ami-07b06b442921831e5'] + - id: image.version + stability: experimental + type: string + brief: > + The version string of the VM image or host OS as defined in + [Version Attributes](/docs/resource/README.md#version-attributes). + examples: ['0.1'] + - id: ip + stability: experimental + type: string[] + brief: > + Available IP addresses of the host, excluding loopback interfaces. + note: > + IPv4 Addresses MUST be specified in dotted-quad notation. IPv6 addresses + MUST be specified in the [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952.html) format. + examples: ["192.168.1.140", "fe80::abc2:4a28:737a:609e"] + - id: mac + stability: experimental + type: string[] + brief: > + Available MAC addresses of the host, excluding loopback interfaces. + note: > + MAC Addresses MUST be represented in [IEEE RA hexadecimal form](https://standards.ieee.org/wp-content/uploads/import/documents/tutorials/eui.pdf): + as hyphen-separated octets in uppercase hexadecimal form from most to least significant. + examples: ['AC-DE-48-23-45-67', 'AC-DE-48-23-45-67-01-9F'] + - id: cpu.vendor.id + stability: experimental + type: string + brief: > + Processor manufacturer identifier. A maximum 12-character string. + note: > + [CPUID](https://wiki.osdev.org/CPUID) command returns the vendor ID string in EBX, EDX and ECX registers. + Writing these to memory in this order results in a 12-character string. + examples: [ 'GenuineIntel' ] + - id: cpu.family + stability: experimental + type: string + brief: > + Family or generation of the CPU. + examples: [ '6', 'PA-RISC 1.1e' ] + - id: cpu.model.id + stability: experimental + type: string + brief: > + Model identifier. It provides more granular information about the CPU, distinguishing it from + other CPUs within the same family. + examples: [ '6', '9000/778/B180L' ] + - id: cpu.model.name + stability: experimental + type: string + brief: > + Model designation of the processor. + examples: [ '11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz' ] + - id: cpu.stepping + stability: experimental + type: string + brief: > + Stepping or core revisions. + examples: ["1", "r1p1"] + - id: cpu.cache.l2.size + stability: experimental + type: int + brief: > + The amount of level 2 memory cache available to the processor (in Bytes). + examples: [ 12288000 ] diff --git a/model/registry/http.yaml b/model/registry/http.yaml new file mode 100644 index 0000000000..e013704a49 --- /dev/null +++ b/model/registry/http.yaml @@ -0,0 +1,174 @@ +groups: + - id: registry.http + prefix: http + type: attribute_group + brief: 'This document defines semantic convention attributes in the HTTP namespace.' + attributes: + - id: request.body.size + type: int + brief: > + The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and + is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) + header. For requests using transport encoding, this should be the compressed size. + examples: 3495 + stability: experimental # this should not be marked stable with other HTTP attributes + - id: request.header + stability: stable + type: template[string[]] + brief: > + HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. + note: > + Instrumentations SHOULD require an explicit configuration of which headers are to be captured. + Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information. + + The `User-Agent` header is already captured in the `user_agent.original` attribute. + Users MAY explicitly configure instrumentations to capture them even though it is not recommended. + + The attribute value MUST consist of either multiple header values as an array of strings + or a single-item array containing a possibly comma-concatenated string, depending on the way + the HTTP library provides access to headers. + examples: ['http.request.header.content-type=["application/json"]', 'http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]'] + - id: request.method + stability: stable + type: + allow_custom_values: true + members: + - id: connect + value: "CONNECT" + brief: 'CONNECT method.' + stability: stable + - id: delete + value: "DELETE" + brief: 'DELETE method.' + stability: stable + - id: get + value: "GET" + brief: 'GET method.' + stability: stable + - id: head + value: "HEAD" + brief: 'HEAD method.' + stability: stable + - id: options + value: "OPTIONS" + brief: 'OPTIONS method.' + stability: stable + - id: patch + value: "PATCH" + brief: 'PATCH method.' + stability: stable + - id: post + value: "POST" + brief: 'POST method.' + stability: stable + - id: put + value: "PUT" + brief: 'PUT method.' + stability: stable + - id: trace + value: "TRACE" + brief: 'TRACE method.' + stability: stable + - id: other + value: "_OTHER" + brief: 'Any HTTP method that the instrumentation has no prior knowledge of.' + stability: stable + brief: 'HTTP request method.' + examples: ["GET", "POST", "HEAD"] + note: | + HTTP request method value SHOULD be "known" to the instrumentation. + By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) + and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). + + If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. + + If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override + the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named + OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods + (this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). + + HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. + Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. + Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. + - id: request.method_original + stability: stable + type: string + brief: Original HTTP method sent by the client in the request line. + examples: ["GeT", "ACL", "foo"] + - id: request.resend_count + stability: stable + type: int + brief: > + The ordinal number of request resending attempt (for any reason, including redirects). + note: > + The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what + was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, + or any other). + examples: 3 + - id: request.size + type: int + brief: > + The total size of the request in bytes. This should be the total number of bytes sent over the wire, including the request line (HTTP/1.1), + framing (HTTP/2 and HTTP/3), headers, and request body if any. + examples: 1437 + stability: experimental + - id: response.body.size + type: int + brief: > + The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and + is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) + header. For requests using transport encoding, this should be the compressed size. + examples: 3495 + stability: experimental # this should not be marked stable with other HTTP attributes + - id: response.header + stability: stable + type: template[string[]] + brief: > + HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. + note: > + Instrumentations SHOULD require an explicit configuration of which headers are to be captured. + Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. + + Users MAY explicitly configure instrumentations to capture them even though it is not recommended. + + The attribute value MUST consist of either multiple header values as an array of strings + or a single-item array containing a possibly comma-concatenated string, depending on the way + the HTTP library provides access to headers. + examples: ['http.response.header.content-type=["application/json"]', 'http.response.header.my-custom-header=["abc", "def"]'] + - id: response.size + type: int + brief: > + The total size of the response in bytes. This should be the total number of bytes sent over the wire, including the status line (HTTP/1.1), + framing (HTTP/2 and HTTP/3), headers, and response body and trailers if any. + examples: 1437 + stability: experimental + - id: response.status_code + stability: stable + type: int + brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).' + examples: [200] + - id: route + stability: stable + type: string + brief: > + The matched route, that is, the path template in the format used by the respective server framework. + examples: ['/users/:userID?', '{controller}/{action}/{id?}'] + note: > + MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. + + SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. + - id: connection.state + type: + allow_custom_values: true + members: + - id: active + value: "active" + brief: 'active state.' + stability: experimental + - id: idle + value: "idle" + brief: 'idle state.' + stability: experimental + brief: State of the HTTP connection in the HTTP connection pool. + stability: experimental + examples: ["active", "idle"] diff --git a/model/registry/jvm.yaml b/model/registry/jvm.yaml new file mode 100644 index 0000000000..071b6c4612 --- /dev/null +++ b/model/registry/jvm.yaml @@ -0,0 +1,81 @@ +groups: + - id: registry.jvm + type: attribute_group + prefix: jvm + brief: > + This document defines Java Virtual machine related attributes. + attributes: + - id: gc.action + stability: stable + type: string + brief: Name of the garbage collector action. + examples: ["end of minor GC", "end of major GC"] + note: > + Garbage collector action is generally obtained via + [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()). + - id: gc.name + stability: stable + type: string + brief: Name of the garbage collector. + examples: ["G1 Young Generation", "G1 Old Generation"] + note: > + Garbage collector name is generally obtained via + [GarbageCollectionNotificationInfo#getGcName()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcName()). + - id: memory.type + stability: stable + type: + allow_custom_values: false + members: + - id: heap + value: 'heap' + brief: 'Heap memory.' + stability: stable + - id: non_heap + value: 'non_heap' + brief: 'Non-heap memory' + stability: stable + brief: The type of memory. + examples: ["heap", "non_heap"] + - id: memory.pool.name + stability: stable + type: string + brief: Name of the memory pool. + examples: ["G1 Old Gen", "G1 Eden space", "G1 Survivor Space"] + note: > + Pool names are generally obtained via + [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). + - id: thread.daemon + stability: stable + type: boolean + brief: "Whether the thread is daemon or not." + - id: thread.state + stability: stable + brief: "State of the thread." + examples: ["runnable", "blocked"] + type: + allow_custom_values: false + members: + - id: new + value: 'new' + brief: 'A thread that has not yet started is in this state.' + stability: stable + - id: runnable + value: 'runnable' + brief: 'A thread executing in the Java virtual machine is in this state.' + stability: stable + - id: blocked + value: 'blocked' + brief: 'A thread that is blocked waiting for a monitor lock is in this state.' + stability: stable + - id: waiting + value: 'waiting' + brief: 'A thread that is waiting indefinitely for another thread to perform a particular action is in this state.' + stability: stable + - id: timed_waiting + value: 'timed_waiting' + brief: 'A thread that is waiting for another thread to perform an action for up to a specified waiting time is in this state.' + stability: stable + - id: terminated + value: 'terminated' + brief: 'A thread that has exited is in this state.' + stability: stable diff --git a/model/registry/k8s.yaml b/model/registry/k8s.yaml new file mode 100644 index 0000000000..013ede5c03 --- /dev/null +++ b/model/registry/k8s.yaml @@ -0,0 +1,178 @@ +groups: + - id: registry.k8s + prefix: k8s + type: attribute_group + brief: > + Kubernetes resource attributes. + attributes: + - id: cluster.name + type: string + stability: experimental + brief: > + The name of the cluster. + examples: ['opentelemetry-cluster'] + - id: cluster.uid + type: string + stability: experimental + brief: > + A pseudo-ID for the cluster, set to the UID of the `kube-system` + namespace. + note: | + K8s doesn't have support for obtaining a cluster ID. If this is ever + added, we will recommend collecting the `k8s.cluster.uid` through the + official APIs. In the meantime, we are able to use the `uid` of the + `kube-system` namespace as a proxy for cluster ID. Read on for the + rationale. + + Every object created in a K8s cluster is assigned a distinct UID. The + `kube-system` namespace is used by Kubernetes itself and will exist + for the lifetime of the cluster. Using the `uid` of the `kube-system` + namespace is a reasonable proxy for the K8s ClusterID as it will only + change if the cluster is rebuilt. Furthermore, Kubernetes UIDs are + UUIDs as standardized by + [ISO/IEC 9834-8 and ITU-T X.667](https://www.itu.int/ITU-T/studygroups/com17/oid.html). + Which states: + + > If generated according to one of the mechanisms defined in Rec. + ITU-T X.667 | ISO/IEC 9834-8, a UUID is either guaranteed to be + different from all other UUIDs generated before 3603 A.D., or is + extremely likely to be different (depending on the mechanism chosen). + + Therefore, UIDs between clusters should be extremely unlikely to + conflict. + examples: ['218fc5a9-a5f1-4b54-aa05-46717d0ab26d'] + - id: node.name + type: string + stability: experimental + brief: > + The name of the Node. + examples: ['node-1'] + - id: node.uid + type: string + stability: experimental + brief: > + The UID of the Node. + examples: ['1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2'] + - id: namespace.name + type: string + stability: experimental + brief: > + The name of the namespace that the pod is running in. + examples: ['default'] + - id: pod.uid + type: string + stability: experimental + brief: > + The UID of the Pod. + examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] + - id: pod.name + type: string + stability: experimental + brief: > + The name of the Pod. + examples: ['opentelemetry-pod-autoconf'] + - id: pod.label + type: template[string] + stability: experimental + brief: > + The label key-value pairs placed on the Pod, the `` being the label name, the value being the label value. + examples: ['k8s.pod.label.app=my-app', 'k8s.pod.label.mycompany.io/arch=x64', 'k8s.pod.label.data='] + - id: pod.annotation + type: template[string] + stability: experimental + brief: > + The annotation key-value pairs placed on the Pod, the `` being the annotation name, the value being the annotation value. + examples: [ 'k8s.pod.annotation.kubernetes.io/enforce-mountable-secrets=true', 'k8s.pod.annotation.mycompany.io/arch=x64', 'k8s.pod.annotation.data=' ] + - id: container.name + type: string + stability: experimental + brief: > + The name of the Container from Pod specification, must be unique + within a Pod. Container runtime usually uses different globally unique + name (`container.name`). + examples: ['redis'] + - id: container.restart_count + type: int + stability: experimental + brief: > + Number of times the container was restarted. This attribute can be + used to identify a particular container (running or stopped) within a + container spec. + - id: container.status.last_terminated_reason + type: string + stability: experimental + brief: > + Last terminated reason of the Container. + examples: ["Evicted", "Error"] + - id: replicaset.uid + type: string + stability: experimental + brief: > + The UID of the ReplicaSet. + examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] + - id: replicaset.name + type: string + stability: experimental + brief: > + The name of the ReplicaSet. + examples: ['opentelemetry'] + - id: deployment.uid + type: string + stability: experimental + brief: > + The UID of the Deployment. + examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] + - id: deployment.name + type: string + stability: experimental + brief: > + The name of the Deployment. + examples: ['opentelemetry'] + - id: statefulset.uid + type: string + stability: experimental + brief: > + The UID of the StatefulSet. + examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] + - id: statefulset.name + type: string + stability: experimental + brief: > + The name of the StatefulSet. + examples: ['opentelemetry'] + - id: daemonset.uid + type: string + stability: experimental + brief: > + The UID of the DaemonSet. + examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] + - id: daemonset.name + type: string + stability: experimental + brief: > + The name of the DaemonSet. + examples: ['opentelemetry'] + - id: job.uid + type: string + stability: experimental + brief: > + The UID of the Job. + examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] + - id: job.name + type: string + stability: experimental + brief: > + The name of the Job. + examples: ['opentelemetry'] + - id: cronjob.uid + type: string + stability: experimental + brief: > + The UID of the CronJob. + examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] + - id: cronjob.name + type: string + stability: experimental + brief: > + The name of the CronJob. + examples: ['opentelemetry'] diff --git a/model/registry/log.yaml b/model/registry/log.yaml new file mode 100644 index 0000000000..b26870a696 --- /dev/null +++ b/model/registry/log.yaml @@ -0,0 +1,72 @@ +groups: + - id: registry.log + type: attribute_group + prefix: log + brief: > + This document defines log attributes + attributes: + - id: iostream + stability: experimental + brief: > + The stream associated with the log. See below for a list of well-known values. + type: + allow_custom_values: true + members: + - id: stdout + value: 'stdout' + brief: 'Logs from stdout stream' + stability: experimental + - id: stderr + value: 'stderr' + brief: 'Events from stderr stream' + stability: experimental + + - id: registry.log.file # TODO: should we move it to the file model? + type: attribute_group + prefix: log.file + brief: > + Attributes for a file to which log was emitted. + attributes: + - id: name + type: string + stability: experimental + brief: > + The basename of the file. + examples: [ "audit.log" ] + - id: path + type: string + stability: experimental + brief: > + The full path to the file. + examples: [ "/var/log/mysql/audit.log" ] + - id: name_resolved + type: string + stability: experimental + brief: > + The basename of the file, with symlinks resolved. + examples: [ "uuid.log" ] + - id: path_resolved + type: string + stability: experimental + brief: > + The full path to the file, with symlinks resolved. + examples: [ "/var/lib/docker/uuid.log" ] + + - id: registry.log.record + type: attribute_group + prefix: log.record + brief: > + This document defines the generic attributes that may be used in any Log Record. + attributes: + - id: uid + type: string + stability: experimental + brief: > + A unique identifier for the Log Record. + note: > + If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. + This means, that two distinguishable log records MUST have different values. + + The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), + but other identifiers (e.g. UUID) may be used as needed. + examples: ["01ARZ3NDEKTSV4RRFFQ69G5FAV"] diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml new file mode 100644 index 0000000000..f22f58f155 --- /dev/null +++ b/model/registry/messaging.yaml @@ -0,0 +1,422 @@ +groups: + - id: registry.messaging + prefix: messaging + type: attribute_group + brief: 'Attributes describing telemetry around messaging systems and messaging activities.' + attributes: + - id: batch.message_count + type: int + stability: experimental + brief: The number of messages sent, received, or processed in the scope of the batching operation. + note: > + 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. + examples: [0, 1, 2] + - id: client_id + type: string + stability: experimental + brief: > + A unique identifier for the client that consumes or produces a message. + examples: ['client-5', 'myhost@8742@s8083jm'] + - id: destination.name + type: string + stability: experimental + brief: 'The message destination name' + note: | + 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'] + - id: destination.template + type: string + stability: experimental + brief: Low cardinality representation of the messaging destination name + note: > + 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. + examples: ['/customers/{customerId}'] + - id: destination.anonymous + type: boolean + stability: experimental + brief: 'A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name).' + - id: destination.temporary + type: boolean + stability: experimental + brief: 'A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed.' + - id: destination_publish.anonymous + type: boolean + stability: experimental + brief: 'A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name).' + - id: destination_publish.name + type: string + stability: experimental + brief: 'The name of the original destination the message was published to' + note: | + 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. + examples: ['MyQueue', 'MyTopic'] + - id: destination.partition.id + type: string + stability: experimental + brief: > + The identifier of the partition messages are sent to or received from, unique within the `messaging.destination.name`. + examples: '1' + - id: message.conversation_id + type: string + stability: experimental + brief: > + The conversation ID identifying the conversation to which the message belongs, + represented as a string. Sometimes called "Correlation ID". + examples: 'MyConversationId' + - id: message.envelope.size + type: int + stability: experimental + brief: > + The size of the message body and metadata in bytes. + note: | + This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed + size should be used. + examples: 2738 + - id: message.id + type: string + stability: experimental + brief: 'A value used by the messaging system as an identifier for the message, represented as a string.' + examples: '452a7c7c7c7048c2f887f61572b18fc2' + - id: message.body.size + type: int + stability: experimental + brief: > + The size of the message body in bytes. + note: | + This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed + body size should be used. + examples: 1439 + - id: operation.type + type: + allow_custom_values: true + members: + - id: publish + value: "publish" + brief: > + 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. + stability: experimental + - id: create + value: "create" + brief: > + 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. + stability: experimental + - id: receive + value: "receive" + brief: > + 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 + value: "process" + brief: > + One or more messages are delivered to or processed by a consumer. + stability: experimental + - id: settle + value: "settle" + brief: > + One or more messages are settled. + stability: experimental + stability: experimental + brief: > + A string identifying the type of the messaging operation. + note: If a custom value is used, it MUST be of low cardinality. + - id: operation.name + type: string + stability: experimental + brief: > + The system-specific name of the messaging operation. + examples: [ "ack", "nack", "send" ] + - id: system + brief: > + An identifier for the messaging system being used. See below for a list of well-known identifiers. + type: + allow_custom_values: true + members: + - id: activemq + value: 'activemq' + brief: 'Apache ActiveMQ' + stability: experimental + - id: aws_sqs + value: 'aws_sqs' + brief: 'Amazon Simple Queue Service (SQS)' + stability: experimental + - id: eventgrid + value: 'eventgrid' + brief: 'Azure Event Grid' + stability: experimental + - id: eventhubs + value: 'eventhubs' + brief: 'Azure Event Hubs' + stability: experimental + - id: servicebus + value: 'servicebus' + brief: 'Azure Service Bus' + stability: experimental + - id: gcp_pubsub + value: 'gcp_pubsub' + brief: 'Google Cloud Pub/Sub' + stability: experimental + - id: jms + value: 'jms' + brief: 'Java Message Service' + stability: experimental + - id: kafka + value: 'kafka' + brief: 'Apache Kafka' + stability: experimental + - id: rabbitmq + value: 'rabbitmq' + brief: 'RabbitMQ' + stability: experimental + - id: rocketmq + value: 'rocketmq' + brief: 'Apache RocketMQ' + stability: experimental + stability: experimental + - id: registry.messaging.kafka + prefix: messaging + type: attribute_group + 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 + brief: > + 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. + note: > + 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. + examples: 'myKey' + - id: kafka.message.offset + type: int + stability: experimental + brief: > + The offset of a record in the corresponding Kafka partition. + examples: 42 + - id: kafka.message.tombstone + type: boolean + stability: experimental + brief: 'A boolean that is true if the message is a tombstone.' + - id: registry.messaging.rabbitmq + prefix: messaging + type: attribute_group + brief: > + This group describes attributes specific to RabbitMQ. + attributes: + - id: rabbitmq.destination.routing_key + type: string + stability: experimental + brief: > + RabbitMQ message routing key. + examples: 'myKey' + - id: rabbitmq.message.delivery_tag + type: int + stability: experimental + brief: > + RabbitMQ message delivery tag + examples: 123 + - id: registry.messaging.rocketmq + prefix: messaging + type: attribute_group + 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 + members: + - id: clustering + value: 'clustering' + brief: 'Clustering consumption model' + stability: experimental + - id: broadcasting + value: 'broadcasting' + brief: 'Broadcasting consumption model' + stability: experimental + stability: experimental + brief: > + Model of message consumption. This only applies to consumer spans. + - id: rocketmq.message.delay_time_level + type: int + stability: experimental + brief: > + The delay time level for delay message, which determines the message delay time. + examples: 3 + - id: rocketmq.message.delivery_timestamp + type: int + stability: experimental + brief: > + The timestamp in milliseconds that the delay message is expected to be delivered to consumer. + examples: 1665987217045 + - id: rocketmq.message.group + type: string + stability: experimental + brief: > + 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. + examples: 'myMessageGroup' + - id: rocketmq.message.keys + type: string[] + stability: experimental + brief: > + Key(s) of message, another way to mark message besides message id. + examples: ['keyA', 'keyB'] + - id: rocketmq.message.tag + type: string + stability: experimental + brief: > + The secondary classifier of message besides topic. + examples: tagA + - id: rocketmq.message.type + type: + allow_custom_values: false + members: + - id: normal + value: 'normal' + brief: "Normal message" + stability: experimental + - id: fifo + value: 'fifo' + brief: 'FIFO message' + stability: experimental + - id: delay + value: 'delay' + brief: 'Delay message' + stability: experimental + - id: transaction + value: 'transaction' + brief: 'Transaction message' + stability: experimental + stability: experimental + brief: > + Type of message. + - id: rocketmq.namespace + type: string + stability: experimental + brief: > + Namespace of RocketMQ resources, resources in different namespaces are individual. + examples: 'myNamespace' + - id: registry.messaging.gcp_pubsub + prefix: messaging + type: attribute_group + brief: > + This group describes attributes specific to GCP Pub/Sub. + attributes: + - id: gcp_pubsub.message.ordering_key + type: string + stability: experimental + brief: > + The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. + examples: 'ordering_key' + tag: tech-specific-gcp-pubsub + - id: gcp_pubsub.message.ack_id + type: string + stability: experimental + brief: > + The ack id for a given message. + examples: 'ack_id' + tag: tech-specific-gcp-pubsub + - id: gcp_pubsub.message.ack_deadline + type: int + stability: experimental + brief: > + The ack deadline in seconds set for the modify ack deadline request. + examples: 10 + tag: tech-specific-gcp-pubsub + - id: gcp_pubsub.message.delivery_attempt + type: int + stability: experimental + brief: > + The delivery attempt for a given message. + examples: 2 + tag: tech-specific-gcp-pubsub + - id: registry.messaging.servicebus + prefix: messaging + type: attribute_group + brief: > + This group describes attributes specific to Azure Service Bus. + attributes: + - id: servicebus.message.delivery_count + type: int + stability: experimental + brief: > + Number of deliveries that have been attempted for this message. + examples: 2 + - id: servicebus.message.enqueued_time + type: int + stability: experimental + 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). + type: + allow_custom_values: true + members: + - id: complete + value: 'complete' + brief: 'Message is completed' + stability: experimental + - id: abandon + value: 'abandon' + brief: 'Message is abandoned' + stability: experimental + - id: dead_letter + value: 'dead_letter' + brief: 'Message is sent to dead letter queue' + stability: experimental + - id: defer + value: 'defer' + brief: 'Message is deferred' + stability: experimental + stability: experimental + - id: registry.messaging.eventhubs + prefix: messaging + type: attribute_group + brief: > + This group describes attributes specific to Azure Event Hubs. + attributes: + - id: eventhubs.message.enqueued_time + type: int + stability: experimental + 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/network.yaml b/model/registry/network.yaml new file mode 100644 index 0000000000..2f3f19576c --- /dev/null +++ b/model/registry/network.yaml @@ -0,0 +1,235 @@ +groups: + - id: registry.network + prefix: network + type: attribute_group + brief: > + These attributes may be used for any network related operation. + attributes: + - id: carrier.icc + type: string + stability: experimental + brief: "The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network." + examples: "DE" + - id: carrier.mcc + type: string + stability: experimental + brief: "The mobile carrier country code." + examples: "310" + - id: carrier.mnc + type: string + stability: experimental + brief: "The mobile carrier network code." + examples: "001" + - id: carrier.name + type: string + stability: experimental + brief: "The name of the mobile carrier." + examples: "sprint" + - id: connection.subtype + type: + allow_custom_values: true + members: + - id: gprs + brief: GPRS + value: "gprs" + stability: experimental + - id: edge + brief: EDGE + value: "edge" + stability: experimental + - id: umts + brief: UMTS + value: "umts" + stability: experimental + - id: cdma + brief: CDMA + value: "cdma" + stability: experimental + - id: evdo_0 + brief: EVDO Rel. 0 + value: "evdo_0" + stability: experimental + - id: evdo_a + brief: "EVDO Rev. A" + value: "evdo_a" + stability: experimental + - id: cdma2000_1xrtt + brief: CDMA2000 1XRTT + value: "cdma2000_1xrtt" + stability: experimental + - id: hsdpa + brief: HSDPA + value: "hsdpa" + stability: experimental + - id: hsupa + brief: HSUPA + value: "hsupa" + stability: experimental + - id: hspa + brief: HSPA + value: "hspa" + stability: experimental + - id: iden + brief: IDEN + value: "iden" + stability: experimental + - id: evdo_b + brief: "EVDO Rev. B" + value: "evdo_b" + stability: experimental + - id: lte + brief: LTE + value: "lte" + stability: experimental + - id: ehrpd + brief: EHRPD + value: "ehrpd" + stability: experimental + - id: hspap + brief: HSPAP + value: "hspap" + stability: experimental + - id: gsm + brief: GSM + value: "gsm" + stability: experimental + - id: td_scdma + brief: TD-SCDMA + value: "td_scdma" + stability: experimental + - id: iwlan + brief: IWLAN + value: "iwlan" + stability: experimental + - id: nr + brief: "5G NR (New Radio)" + value: "nr" + stability: experimental + - id: nrnsa + brief: "5G NRNSA (New Radio Non-Standalone)" + value: "nrnsa" + stability: experimental + - id: lte_ca + brief: LTE CA + value: "lte_ca" + stability: experimental + stability: experimental + brief: 'This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection.' + examples: 'LTE' + - id: connection.type + type: + allow_custom_values: true + members: + - id: wifi + value: "wifi" + stability: experimental + - id: wired + value: "wired" + stability: experimental + - id: cell + value: "cell" + stability: experimental + - id: unavailable + value: "unavailable" + stability: experimental + - id: unknown + value: "unknown" + stability: experimental + stability: experimental + brief: 'The internet connection type.' + examples: 'wifi' + - id: local.address + stability: stable + type: string + brief: Local address of the network connection - IP address or Unix domain socket name. + examples: ['10.1.2.80', '/tmp/my.sock'] + - id: local.port + stability: stable + type: int + brief: Local port number of the network connection. + examples: [65123] + - id: peer.address + stability: stable + type: string + brief: Peer address of the network connection - IP address or Unix domain socket name. + examples: ['10.1.2.80', '/tmp/my.sock'] + - id: peer.port + stability: stable + type: int + brief: Peer port number of the network connection. + examples: [65123] + - id: protocol.name + stability: stable + type: string + brief: '[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent.' + note: The value SHOULD be normalized to lowercase. + examples: ['amqp', 'http', 'mqtt'] + - id: protocol.version + stability: stable + type: string + brief: The actual version of the protocol used for network communication. + examples: ['1.1', '2'] + note: > + If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), + this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, + this attribute SHOULD NOT be set. + - id: transport + stability: stable + type: + allow_custom_values: true + members: + - id: tcp + value: 'tcp' + brief: "TCP" + stability: stable + - id: udp + value: 'udp' + brief: "UDP" + stability: stable + - id: pipe + value: "pipe" + brief: 'Named or anonymous pipe.' + stability: stable + - id: unix + value: 'unix' + brief: "Unix domain socket" + stability: stable + brief: > + [OSI transport layer](https://osi-model.com/transport-layer/) or + [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + note: | + The value SHOULD be normalized to lowercase. + + Consider always setting the transport when setting a port number, since + a port number is ambiguous without knowing the transport. For example + different processes could be listening on TCP port 12345 and UDP port 12345. + examples: ['tcp', 'udp'] + - id: type + stability: stable + type: + allow_custom_values: true + members: + - id: ipv4 + value: 'ipv4' + brief: "IPv4" + stability: stable + - id: ipv6 + value: 'ipv6' + brief: "IPv6" + stability: stable + brief: '[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent.' + note: The value SHOULD be normalized to lowercase. + examples: ['ipv4', 'ipv6'] + - id: io.direction + type: + allow_custom_values: false + members: + - id: transmit + value: 'transmit' + stability: experimental + - id: receive + value: 'receive' + stability: experimental + stability: experimental + brief: "The network IO operation direction." + examples: ["transmit"] diff --git a/model/registry/oci.yaml b/model/registry/oci.yaml new file mode 100644 index 0000000000..00d0e28c2b --- /dev/null +++ b/model/registry/oci.yaml @@ -0,0 +1,22 @@ +groups: + - id: registry.oci.manifest + prefix: oci.manifest + type: attribute_group + brief: > + An OCI image manifest. + attributes: + - id: digest + type: string + stability: experimental + brief: > + The digest of the OCI image manifest. For container images specifically is the + digest by which the container image is known. + note: > + Follows + [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md), + and specifically the + [Digest property](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests). + + An example can be found in + [Example Image Manifest](https://docs.docker.com/registry/spec/manifest-v2-2/#example-image-manifest). + examples: [ 'sha256:e4ca62c0d62f3e886e684806dfe9d4e0cda60d54986898173c1083856cfda0f4' ] diff --git a/model/registry/opentracing.yaml b/model/registry/opentracing.yaml new file mode 100644 index 0000000000..fd9d68e380 --- /dev/null +++ b/model/registry/opentracing.yaml @@ -0,0 +1,22 @@ +groups: + - id: registry.opentracing + prefix: opentracing + type: attribute_group + brief: Attributes used by the OpenTracing Shim layer. + attributes: + - id: ref_type + brief: 'Parent-child Reference type' + stability: experimental + note: > + The causal relationship between a child Span and a parent Span. + type: + allow_custom_values: true + members: + - id: child_of + value: 'child_of' + brief: "The parent Span depends on the child Span in some capacity" + stability: experimental + - id: follows_from + value: 'follows_from' + brief: "The parent Span doesn't depend in any way on the result of the child Span" + stability: experimental diff --git a/model/registry/os.yaml b/model/registry/os.yaml new file mode 100644 index 0000000000..3317958f16 --- /dev/null +++ b/model/registry/os.yaml @@ -0,0 +1,85 @@ +groups: + - id: registry.os + prefix: os + type: attribute_group + brief: > + The operating system (OS) on which the process represented by this resource is running. + note: > + In case of virtualized environments, this is the operating system as it is observed by + the process, i.e., the virtualized guest rather than the underlying host. + attributes: + - id: type + type: + allow_custom_values: true + members: + - id: windows + value: 'windows' + brief: "Microsoft Windows" + stability: experimental + - id: linux + value: 'linux' + brief: "Linux" + stability: experimental + - id: darwin + value: 'darwin' + brief: "Apple Darwin" + stability: experimental + - id: freebsd + value: 'freebsd' + brief: "FreeBSD" + stability: experimental + - id: netbsd + value: 'netbsd' + brief: "NetBSD" + stability: experimental + - id: openbsd + value: 'openbsd' + brief: "OpenBSD" + stability: experimental + - id: dragonflybsd + value: 'dragonflybsd' + brief: "DragonFly BSD" + stability: experimental + - id: hpux + value: 'hpux' + brief: "HP-UX (Hewlett Packard Unix)" + stability: experimental + - id: aix + value: 'aix' + brief: "AIX (Advanced Interactive eXecutive)" + stability: experimental + - id: solaris + value: 'solaris' + brief: "SunOS, Oracle Solaris" + stability: experimental + - id: z_os + value: 'z_os' + brief: "IBM z/OS" + stability: experimental + brief: > + The operating system type. + stability: experimental + - id: description + type: string + stability: experimental + brief: > + Human readable (not intended to be parsed) OS version information, + like e.g. reported by `ver` or `lsb_release -a` commands. + examples: ['Microsoft Windows [Version 10.0.18363.778]', 'Ubuntu 18.04.1 LTS'] + - id: name + type: string + stability: experimental + brief: 'Human readable operating system name.' + examples: ['iOS', 'Android', 'Ubuntu'] + - id: version + type: string + stability: experimental + brief: > + The version string of the operating system as defined in + [Version Attributes](/docs/resource/README.md#version-attributes). + examples: ['14.2.1', '18.04.1'] + - id: build_id + type: string + stability: experimental + brief: 'Unique identifier for a particular build or compilation of the operating system.' + examples: ['TQ3C.230805.001.B2', '20E247', '22621'] diff --git a/model/registry/otel.yaml b/model/registry/otel.yaml new file mode 100644 index 0000000000..76286cdc9b --- /dev/null +++ b/model/registry/otel.yaml @@ -0,0 +1,40 @@ +groups: + - id: registry.otel + prefix: otel + type: attribute_group + brief: Attributes reserved for OpenTelemetry + attributes: + - id: status_code + type: + allow_custom_values: true + members: + - id: ok + value: OK + brief: 'The operation has been validated by an Application developer or Operator to have completed successfully.' + stability: stable + - id: error + value: ERROR + brief: 'The operation contains an error.' + stability: stable + brief: Name of the code, either "OK" or "ERROR". MUST NOT be set if the status code is UNSET. + stability: stable + - id: status_description + type: string + brief: "Description of the Status if it has a value, otherwise not set." + examples: ['resource not found'] + stability: stable + - id: registry.otel.scope + prefix: otel.scope + type: attribute_group + brief: Attributes used by non-OTLP exporters to represent OpenTelemetry Scope's concepts. + attributes: + - id: name + type: string + brief: The name of the instrumentation scope - (`InstrumentationScope.Name` in OTLP). + examples: ['io.opentelemetry.contrib.mongodb'] + stability: stable + - id: version + type: string + brief: The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). + examples: ['1.0.0'] + stability: stable diff --git a/model/registry/peer.yaml b/model/registry/peer.yaml new file mode 100644 index 0000000000..a6e38a129d --- /dev/null +++ b/model/registry/peer.yaml @@ -0,0 +1,15 @@ +groups: + - id: registry.peer + type: attribute_group + prefix: peer + brief: > + Operations that access some remote service. + attributes: + - id: service + type: string + stability: experimental + brief: > + The [`service.name`](/docs/resource/README.md#service) + of the remote service. SHOULD be equal to the actual `service.name` + resource attribute of the remote service if any. + examples: "AuthTokenCache" diff --git a/model/registry/process.yaml b/model/registry/process.yaml new file mode 100644 index 0000000000..bccb070551 --- /dev/null +++ b/model/registry/process.yaml @@ -0,0 +1,172 @@ +groups: + - id: registry.process + prefix: process + type: attribute_group + brief: > + An operating system process. + attributes: + - id: pid + type: int + stability: experimental + brief: > + Process identifier (PID). + examples: [1234] + - id: parent_pid + type: int + stability: experimental + brief: > + Parent Process identifier (PPID). + examples: [111] + - id: vpid + type: int + stability: experimental + brief: > + Virtual process identifier. + note: > + The process ID within a PID namespace. This is not necessarily unique + across all processes on the host but it is unique within the process + namespace that the process exists within. + examples: [12] + - id: session_leader.pid + type: int + stability: experimental + brief: > + The PID of the process's session leader. This is also the session ID + (SID) of the process. + examples: [14] + - id: group_leader.pid + type: int + stability: experimental + brief: > + The PID of the process's group leader. This is also the process group + ID (PGID) of the process. + examples: [23] + - id: executable.name + type: string + stability: experimental + brief: > + The name of the process executable. On Linux based systems, can be set + to the `Name` in `proc/[pid]/status`. On Windows, can be set to the + base name of `GetProcessImageFileNameW`. + examples: ['otelcol'] + - id: executable.path + type: string + stability: experimental + brief: > + The full path to the process executable. On Linux based systems, can + be set to the target of `proc/[pid]/exe`. On Windows, can be set to the + result of `GetProcessImageFileNameW`. + examples: ['/usr/bin/cmd/otelcol'] + - id: command + type: string + stability: experimental + brief: > + The command used to launch the process (i.e. the command name). On Linux + based systems, can be set to the zeroth string in `proc/[pid]/cmdline`. + On Windows, can be set to the first parameter extracted from `GetCommandLineW`. + examples: ['cmd/otelcol'] + - id: command_line + type: string + stability: experimental + brief: > + The full command used to launch the process as a single string representing + the full command. On Windows, can be set to the result of `GetCommandLineW`. + Do not set this if you have to assemble it just for monitoring; use + `process.command_args` instead. + examples: ['C:\cmd\otecol --config="my directory\config.yaml"'] + - id: command_args + type: string[] + stability: experimental + brief: > + All the command arguments (including the command/executable itself) as + received by the process. On Linux-based systems (and some other Unixoid + systems supporting procfs), can be set according to the list of + null-delimited strings extracted from `proc/[pid]/cmdline`. For libc-based + executables, this would be the full argv vector passed to `main`. + examples: ['cmd/otecol', '--config=config.yaml'] + - id: owner + type: string + stability: experimental + brief: > + The username of the user that owns the process. + examples: ['root'] + - id: user.id + type: int + stability: experimental + brief: > + The effective user ID (EUID) of the process. + examples: [1001] + - id: user.name + type: string + stability: experimental + brief: > + The username of the effective user of the process. + examples: ['root'] + - id: real_user.id + type: int + stability: experimental + brief: > + The real user ID (RUID) of the process. + examples: [1000] + - id: real_user.name + type: string + stability: experimental + brief: > + The username of the real user of the process. + examples: ['operator'] + - id: saved_user.id + type: int + stability: experimental + brief: > + The saved user ID (SUID) of the process. + examples: [1002] + - id: saved_user.name + type: string + stability: experimental + brief: > + The username of the saved user. + examples: ['operator'] + - id: runtime.name + 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. + examples: ['OpenJDK Runtime Environment'] + - id: runtime.version + type: string + stability: experimental + brief: > + The version of the runtime of this process, as returned by the runtime + without modification. + examples: '14.0.2' + - id: runtime.description + type: string + stability: experimental + brief: > + An additional description about the runtime of the process, for example + a specific vendor customization of the runtime environment. + examples: 'Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0' + - id: creation.time + type: string + stability: experimental + brief: > + The date and time the process was created, in ISO 8601 format. + examples: ['2023-11-21T09:25:34.853Z'] + - id: exit.time + type: string + stability: experimental + brief: > + The date and time the process exited, in ISO 8601 format. + examples: ['2023-11-21T09:26:12.315Z'] + - id: exit.code + type: int + stability: experimental + brief: > + The exit code of the process. + examples: [127] + - id: interactive + type: boolean + stability: experimental + brief: > + Whether the process is connected to an interactive shell. diff --git a/model/registry/rpc.yaml b/model/registry/rpc.yaml new file mode 100644 index 0000000000..d1e0aa05cf --- /dev/null +++ b/model/registry/rpc.yaml @@ -0,0 +1,265 @@ +groups: + - id: registry.rpc + prefix: rpc + type: attribute_group + brief: 'This document defines attributes for remote procedure calls.' + attributes: + - id: connect_rpc.error_code + type: + members: + - id: cancelled + value: cancelled + stability: experimental + - id: unknown + value: unknown + stability: experimental + - id: invalid_argument + value: invalid_argument + stability: experimental + - id: deadline_exceeded + value: deadline_exceeded + stability: experimental + - id: not_found + value: not_found + stability: experimental + - id: already_exists + value: already_exists + stability: experimental + - id: permission_denied + value: permission_denied + stability: experimental + - id: resource_exhausted + value: resource_exhausted + stability: experimental + - id: failed_precondition + value: failed_precondition + stability: experimental + - id: aborted + value: aborted + stability: experimental + - id: out_of_range + value: out_of_range + stability: experimental + - id: unimplemented + value: unimplemented + stability: experimental + - id: internal + value: internal + stability: experimental + - id: unavailable + value: unavailable + stability: experimental + - id: data_loss + value: data_loss + stability: experimental + - id: unauthenticated + value: unauthenticated + stability: experimental + stability: experimental + brief: "The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values." + - id: connect_rpc.request.metadata + type: template[string[]] + stability: experimental + brief: > + Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + note: > + Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. + Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + examples: ['rpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]'] + - id: connect_rpc.response.metadata + type: template[string[]] + stability: experimental + brief: > + Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + note: > + Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. + Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + examples: ['rpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]'] + - id: grpc.status_code + type: + members: + - id: ok + brief: OK + stability: experimental + value: 0 + - id: cancelled + brief: CANCELLED + stability: experimental + value: 1 + - id: unknown + brief: UNKNOWN + stability: experimental + value: 2 + - id: invalid_argument + brief: INVALID_ARGUMENT + stability: experimental + value: 3 + - id: deadline_exceeded + brief: DEADLINE_EXCEEDED + stability: experimental + value: 4 + - id: not_found + brief: NOT_FOUND + stability: experimental + value: 5 + - id: already_exists + brief: ALREADY_EXISTS + stability: experimental + value: 6 + - id: permission_denied + brief: PERMISSION_DENIED + stability: experimental + value: 7 + - id: resource_exhausted + brief: RESOURCE_EXHAUSTED + stability: experimental + value: 8 + - id: failed_precondition + brief: FAILED_PRECONDITION + stability: experimental + value: 9 + - id: aborted + brief: ABORTED + stability: experimental + value: 10 + - id: out_of_range + brief: OUT_OF_RANGE + stability: experimental + value: 11 + - id: unimplemented + brief: UNIMPLEMENTED + stability: experimental + value: 12 + - id: internal + brief: INTERNAL + stability: experimental + value: 13 + - id: unavailable + brief: UNAVAILABLE + stability: experimental + value: 14 + - id: data_loss + brief: DATA_LOSS + stability: experimental + value: 15 + - id: unauthenticated + brief: UNAUTHENTICATED + stability: experimental + value: 16 + stability: experimental + brief: "The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request." + - id: grpc.request.metadata + type: template[string[]] + stability: experimental + brief: > + gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + note: > + Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. + Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + examples: ['rpc.grpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]'] + - id: grpc.response.metadata + type: template[string[]] + stability: experimental + brief: > + gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + note: > + Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. + Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + examples: ['rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]'] + - id: jsonrpc.error_code + type: int + stability: experimental + brief: "`error.code` property of response if it is an error response." + examples: [-32700, 100] + - id: jsonrpc.error_message + type: string + stability: experimental + brief: "`error.message` property of response if it is an error response." + examples: ['Parse error', 'User already exists'] + - id: jsonrpc.request_id + type: string + stability: experimental + brief: > + `id` property of request or response. + Since protocol allows id to be int, string, `null` or missing (for notifications), + value is expected to be cast to string for simplicity. + Use empty string in case of `null` value. Omit entirely if this is a notification. + examples: ['10', 'request-7', ''] + - id: jsonrpc.version + type: string + stability: experimental + brief: "Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted." + examples: ['2.0', '1.0'] + - id: method + type: string + stability: experimental + brief: 'The name of the (logical) method being called, must be equal to the $method part in the span name.' + note: > + This is the logical name of the method from the RPC interface perspective, + which can be different from the name of any implementing method/function. + The `code.function` attribute may be used to store the latter + (e.g., method actually executing the call on the server side, + RPC client stub method on the client side). + examples: "exampleMethod" + - id: service + type: string + stability: experimental + brief: 'The full (logical) name of the service being called, including its package name, if applicable.' + note: > + This is the logical name of the service from the RPC interface perspective, + which can be different from the name of any implementing class. + The `code.namespace` attribute may be used to store the latter + (despite the attribute name, it may include a class name; + e.g., class with method actually executing the call on the server side, + RPC client stub class on the client side). + examples: "myservice.EchoService" + - id: system + brief: 'A string identifying the remoting system. See below for a list of well-known identifiers.' + type: + allow_custom_values: true + members: + - id: grpc + value: 'grpc' + brief: 'gRPC' + stability: experimental + - id: java_rmi + value: 'java_rmi' + brief: 'Java RMI' + stability: experimental + - id: dotnet_wcf + value: 'dotnet_wcf' + brief: '.NET WCF' + stability: experimental + - id: apache_dubbo + value: 'apache_dubbo' + brief: 'Apache Dubbo' + stability: experimental + - id: connect_rpc + value: 'connect_rpc' + brief: 'Connect RPC' + stability: experimental + stability: experimental + - id: message.type + type: + members: + - id: sent + value: "SENT" + stability: experimental + - id: received + value: "RECEIVED" + stability: experimental + stability: experimental + brief: "Whether this is a received or sent message." + - id: message.id + type: int + stability: experimental + brief: "MUST be calculated as two different counters starting from `1` one for sent messages and one for received message." + note: "This way we guarantee that the values will be consistent between different implementations." + - id: message.compressed_size + type: int + stability: experimental + brief: "Compressed size of the message in bytes." + - id: message.uncompressed_size + type: int + stability: experimental + brief: "Uncompressed size of the message in bytes." diff --git a/model/registry/server.yaml b/model/registry/server.yaml new file mode 100644 index 0000000000..d6927fe98a --- /dev/null +++ b/model/registry/server.yaml @@ -0,0 +1,28 @@ +groups: + - id: registry.server + prefix: server + type: attribute_group + brief: > + These attributes may be used to describe the server in a connection-based network interaction + where there is one side that initiates the connection (the client is the side that initiates the connection). + This covers all TCP network interactions since TCP is connection-based and one side initiates the + connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the + protocol / API doesn't expose a clear notion of client and server). + This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS. + attributes: + - id: address + stability: stable + type: string + brief: "Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name." + note: > + 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. + examples: ['example.com', '10.1.2.80', '/tmp/my.sock'] + - id: port + stability: stable + type: int + brief: Server port number. + note: > + 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. + examples: [80, 8080, 443] diff --git a/model/registry/service.yaml b/model/registry/service.yaml new file mode 100644 index 0000000000..5af22be57e --- /dev/null +++ b/model/registry/service.yaml @@ -0,0 +1,71 @@ +groups: + - id: registry.service + prefix: service + type: attribute_group + brief: > + A service instance. + attributes: + - id: name + type: string + brief: > + Logical name of the service. + note: > + MUST be the same for all instances of horizontally scaled services. + If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated + with [`process.executable.name`](process.md), e.g. `unknown_service:bash`. + If `process.executable.name` is not available, the value MUST be set to `unknown_service`. + examples: ["shoppingcart"] + stability: stable + - id: version + type: string + brief: > + The version string of the service API or implementation. The format is not defined by these conventions. + examples: ["2.0.0", "a01dbef8a"] + stability: stable + - id: namespace + type: string + stability: experimental + brief: > + A namespace for `service.name`. + note: > + A string value having a meaning that helps to distinguish a group of services, + for example the team name that owns a group of services. + `service.name` is expected to be unique within the same namespace. + If `service.namespace` is not specified in the Resource then `service.name` + is expected to be unique for all services that have no explicit namespace defined + (so the empty/unspecified namespace is simply one more valid namespace). + Zero-length namespace string is assumed equal to unspecified namespace. + examples: ["Shop"] + - id: instance.id + type: string + stability: experimental + brief: > + The string ID of the service instance. + note: | + MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words + `service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to + distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled + service). + + Implementations, such as SDKs, are recommended to generate a random Version 1 or Version 4 [RFC + 4122](https://www.ietf.org/rfc/rfc4122.txt) UUID, but are free to use an inherent unique ID as the source of + this value if stability is desirable. In that case, the ID SHOULD be used as source of a UUID Version 5 and + SHOULD use the following UUID as the namespace: `4d63009a-8d0f-11ee-aad7-4c796ed8e320`. + + UUIDs are typically recommended, as only an opaque value for the purposes of identifying a service instance is + needed. Similar to what can be seen in the man page for the + [`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/machine-id.html) file, the underlying + data, such as pod name and namespace should be treated as confidential, being the user's choice to expose it + or not via another resource attribute. + + For applications running behind an application server (like unicorn), we do not recommend using one identifier + for all processes participating in the application. Instead, it's recommended each division (e.g. a worker + thread in unicorn) to have its own instance.id. + + It's not recommended for a Collector to set `service.instance.id` if it can't unambiguously determine the + service instance that is generating that telemetry. For instance, creating an UUID based on `pod.name` will + likely be wrong, as the Collector might not know from which container within that pod the telemetry originated. + However, Collectors can set the `service.instance.id` if they can unambiguously determine the service instance + for that telemetry. This is typically the case for scraping receivers, as they know the target address and + port. + examples: ["627cc493-f310-47de-96bd-71410b7dec09"] diff --git a/model/registry/session.yaml b/model/registry/session.yaml new file mode 100644 index 0000000000..3f53c9c6cd --- /dev/null +++ b/model/registry/session.yaml @@ -0,0 +1,26 @@ +groups: + - id: registry.session + prefix: session + type: attribute_group + brief: > + Session is defined as the period of time encompassing all activities performed by the application and the actions + executed by the end user. + + Consequently, a Session is represented as a collection of Logs, Events, and Spans emitted by the Client Application + throughout the Session's duration. Each Session is assigned a unique identifier, which is included as an attribute in + the Logs, Events, and Spans generated during the Session's lifecycle. + + When a session reaches end of life, typically due to user inactivity or session timeout, a new session identifier + will be assigned. The previous session identifier may be provided by the instrumentation so that telemetry + backends can link the two sessions. + attributes: + - id: id + type: string + stability: experimental + brief: "A unique id to identify a session." + examples: "00112233-4455-6677-8899-aabbccddeeff" + - id: previous_id + type: string + stability: experimental + brief: "The previous `session.id` for this user, when known." + examples: "00112233-4455-6677-8899-aabbccddeeff" diff --git a/model/registry/signalr.yaml b/model/registry/signalr.yaml new file mode 100644 index 0000000000..879034e7b3 --- /dev/null +++ b/model/registry/signalr.yaml @@ -0,0 +1,43 @@ +groups: + - id: registry.signalr + prefix: signalr + type: attribute_group + brief: SignalR attributes + attributes: + - id: connection.status + type: + members: + - id: normal_closure + value: 'normal_closure' + brief: "The connection was closed normally." + stability: stable + - id: timeout + value: 'timeout' + brief: "The connection was closed due to a timeout." + stability: stable + - id: app_shutdown + value: 'app_shutdown' + brief: "The connection was closed because the app is shutting down." + stability: stable + stability: stable + brief: SignalR HTTP connection closure status. + examples: ["app_shutdown", "timeout"] + - id: transport + brief: "[SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md)" + type: + allow_custom_values: true + members: + - id: server_sent_events + value: 'server_sent_events' + brief: "ServerSentEvents protocol" + stability: stable + - id: long_polling + value: 'long_polling' + brief: "LongPolling protocol" + stability: stable + - id: web_sockets + value: 'web_sockets' + brief: "WebSockets protocol" + stability: stable + stability: stable + examples: ["web_sockets", "long_polling"] diff --git a/model/registry/source.yaml b/model/registry/source.yaml new file mode 100644 index 0000000000..077da82310 --- /dev/null +++ b/model/registry/source.yaml @@ -0,0 +1,25 @@ +groups: + - id: registry.source + prefix: source + type: attribute_group + brief: > + These attributes may be used to describe the sender of a network exchange/packet. These should be used + when there is no client/server relationship between the two sides, or when that relationship is unknown. + This covers low-level network interactions (e.g. packet tracing) where you don't know if + there was a connection or which side initiated it. + This also covers unidirectional UDP flows and peer-to-peer communication where the + "user-facing" surface of the protocol / API doesn't expose a clear notion of client and server. + attributes: + - id: address + type: string + stability: experimental + brief: "Source address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name." + note: > + When observed from the destination side, and when communicating through an intermediary, `source.address` SHOULD represent + the source address behind any intermediaries, for example proxies, if it's available. + examples: ['source.example.com', '10.1.2.80', '/tmp/my.sock'] + - id: port + type: int + stability: experimental + brief: 'Source port number' + examples: [3389, 2888] diff --git a/model/registry/system.yaml b/model/registry/system.yaml new file mode 100644 index 0000000000..0766d4c8b2 --- /dev/null +++ b/model/registry/system.yaml @@ -0,0 +1,256 @@ +groups: + # General system attributes + - id: registry.system + prefix: system + type: attribute_group + brief: "Describes System attributes" + attributes: + - id: device + type: string + stability: experimental + brief: "The device identifier" + examples: ["(identifier)"] + # system.cpu.* attribute group + - id: registry.system.cpu + prefix: system.cpu + 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 + brief: "The logical CPU number [0..n-1]" + examples: [1] + # sytem.memory.* attribute group + - id: registry.system.memory + prefix: system.memory + type: attribute_group + brief: "Describes System Memory attributes" + attributes: + - id: state + type: + allow_custom_values: true + members: + - id: used + value: 'used' + stability: experimental + - id: free + value: 'free' + stability: experimental + - id: shared + value: 'shared' + stability: experimental + deprecated: 'Removed, report shared memory usage with `metric.system.memory.shared` metric' + - id: buffers + value: 'buffers' + stability: experimental + - id: cached + value: 'cached' + stability: experimental + stability: experimental + brief: "The memory state" + examples: ["free", "cached"] + # system.paging.* attribute group + - id: registry.system.paging + prefix: system.paging + type: attribute_group + brief: "Describes System Memory Paging attributes" + attributes: + - id: state + type: + allow_custom_values: false + members: + - id: used + value: 'used' + stability: experimental + - id: free + value: 'free' + stability: experimental + stability: experimental + brief: "The memory paging state" + examples: ["free"] + - id: type + type: + allow_custom_values: false + members: + - id: major + value: 'major' + stability: experimental + - id: minor + value: 'minor' + stability: experimental + stability: experimental + brief: "The memory paging type" + examples: ["minor"] + - id: direction + type: + allow_custom_values: false + members: + - id: in + value: 'in' + stability: experimental + - id: out + value: 'out' + stability: experimental + stability: experimental + brief: "The paging access direction" + examples: ["in"] + - id: registry.system.filesystem + prefix: system.filesystem + type: attribute_group + brief: "Describes Filesystem attributes" + attributes: + - id: state + brief: "The filesystem state" + type: + allow_custom_values: false + members: + - id: used + value: 'used' + stability: experimental + - id: free + value: 'free' + stability: experimental + - id: reserved + value: 'reserved' + stability: experimental + stability: experimental + examples: ["used"] + - id: type + type: + allow_custom_values: true + members: + - id: fat32 + value: 'fat32' + stability: experimental + - id: exfat + value: 'exfat' + stability: experimental + - id: ntfs + value: 'ntfs' + stability: experimental + - id: refs + value: 'refs' + stability: experimental + - id: hfsplus + value: 'hfsplus' + stability: experimental + - id: ext4 + value: 'ext4' + stability: experimental + stability: experimental + brief: "The filesystem type" + examples: ["ext4"] + - id: mode + type: string + stability: experimental + brief: "The filesystem mode" + examples: ["rw, ro"] + - id: mountpoint + type: string + stability: experimental + brief: "The filesystem mount path" + examples: ["/mnt/data"] + # System-specific network attributes + - id: registry.system.network + prefix: system.network + type: attribute_group + brief: "Describes Network attributes" + attributes: + - id: state + type: + allow_custom_values: false + members: + - id: close + value: 'close' + stability: experimental + - id: close_wait + value: 'close_wait' + stability: experimental + - id: closing + value: 'closing' + stability: experimental + - id: delete + value: 'delete' + stability: experimental + - id: established + value: 'established' + stability: experimental + - id: fin_wait_1 + value: 'fin_wait_1' + stability: experimental + - id: fin_wait_2 + value: 'fin_wait_2' + stability: experimental + - id: last_ack + value: 'last_ack' + stability: experimental + - id: listen + value: 'listen' + stability: experimental + - id: syn_recv + value: 'syn_recv' + stability: experimental + - id: syn_sent + value: 'syn_sent' + stability: experimental + - id: time_wait + value: 'time_wait' + stability: experimental + stability: experimental + brief: "A stateless protocol MUST NOT set this attribute" + examples: ["close_wait"] + # system.process.* attribute group + - id: registry.system.process + prefix: system.process + type: attribute_group + brief: "Describes System Process attributes" + attributes: + - id: status + type: + allow_custom_values: true + members: + - id: running + value: 'running' + stability: experimental + - id: sleeping + value: 'sleeping' + stability: experimental + - id: stopped + value: 'stopped' + stability: experimental + - id: defunct + value: 'defunct' + stability: experimental + stability: experimental + brief: > + The process state, e.g., [Linux Process State Codes](https://man7.org/linux/man-pages/man1/ps.1.html#PROCESS_STATE_CODES) + examples: ["running"] diff --git a/model/registry/telemetry.yaml b/model/registry/telemetry.yaml new file mode 100644 index 0000000000..2179330323 --- /dev/null +++ b/model/registry/telemetry.yaml @@ -0,0 +1,87 @@ +groups: + - id: registry.telemetry + prefix: telemetry + type: attribute_group + brief: > + This document defines attributes for telemetry SDK. + attributes: + - id: sdk.name + type: string + stability: stable + requirement_level: required + brief: > + The name of the telemetry SDK as defined above. + note: | + The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. + If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the + `telemetry.sdk.name` attribute to the fully-qualified class or module name of this SDK's main entry point + or another suitable identifier depending on the language. + The identifier `opentelemetry` is reserved and MUST NOT be used in this case. + All custom identifiers SHOULD be stable across different versions of an implementation. + examples: ["opentelemetry"] + - id: sdk.language + type: + allow_custom_values: true + members: + - id: cpp + value: "cpp" + stability: stable + - id: dotnet + value: "dotnet" + stability: stable + - id: erlang + value: "erlang" + stability: stable + - id: go + value: "go" + stability: stable + - id: java + value: "java" + stability: stable + - id: nodejs + value: "nodejs" + stability: stable + - id: php + value: "php" + stability: stable + - id: python + value: "python" + stability: stable + - id: ruby + value: "ruby" + stability: stable + - id: rust + value: "rust" + stability: stable + - id: swift + value: "swift" + stability: stable + - id: webjs + value: "webjs" + stability: stable + stability: stable + requirement_level: required + brief: > + The language of the telemetry SDK. + - id: sdk.version + type: string + stability: stable + requirement_level: required + brief: > + The version string of the telemetry SDK. + examples: ["1.2.3"] + - id: distro.name + type: string + stability: experimental + brief: > + The name of the auto instrumentation agent or distribution, if used. + note: | + Official auto instrumentation agents and distributions SHOULD set the `telemetry.distro.name` attribute to + a string starting with `opentelemetry-`, e.g. `opentelemetry-java-instrumentation`. + examples: ["parts-unlimited-java"] + - id: distro.version + type: string + stability: experimental + brief: > + The version string of the auto instrumentation agent or distribution, if used. + examples: ["1.2.3"] diff --git a/model/registry/thread.yaml b/model/registry/thread.yaml new file mode 100644 index 0000000000..9c99772b9b --- /dev/null +++ b/model/registry/thread.yaml @@ -0,0 +1,19 @@ +groups: + - id: registry.thread + prefix: thread + type: attribute_group + brief: > + These attributes may be used for any operation to store information about a thread that started a span. + attributes: + - id: id + type: int + stability: experimental + brief: > + Current "managed" thread ID (as opposed to OS thread ID). + examples: 42 + - id: name + type: string + stability: experimental + brief: > + Current thread name. + examples: main diff --git a/model/registry/tls.yaml b/model/registry/tls.yaml new file mode 100644 index 0000000000..d327cf5005 --- /dev/null +++ b/model/registry/tls.yaml @@ -0,0 +1,196 @@ +groups: + - id: registry.tls + prefix: tls + type: attribute_group + brief: "This document defines semantic convention attributes in the TLS namespace." + attributes: + - id: cipher + brief: > + String indicating the [cipher](https://datatracker.ietf.org/doc/html/rfc5246#appendix-A.5) used during the current connection. + type: string + stability: experimental + note: > + The values allowed for `tls.cipher` MUST be one of the `Descriptions` of the + [registered TLS Cipher Suits](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#table-tls-parameters-4). + examples: + [ + "TLS_RSA_WITH_3DES_EDE_CBC_SHA", + "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256", + ] + - id: client.certificate + type: string + stability: experimental + brief: > + PEM-encoded stand-alone certificate offered by the client. This is usually mutually-exclusive of `client.certificate_chain` since this value also exists in that list. + examples: ["MII..."] + - id: client.certificate_chain + type: string[] + stability: experimental + brief: > + Array of PEM-encoded certificates that make up the certificate chain offered by the client. + This is usually mutually-exclusive of `client.certificate` since that value should be the first certificate in the chain. + examples: ["MII...", "MI..."] + - id: client.hash.md5 + type: string + stability: experimental + brief: > + Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the client. + For consistency with other hash values, this value should be formatted as an uppercase hash. + examples: ["0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC"] + - id: client.hash.sha1 + type: string + stability: experimental + brief: > + Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the client. + For consistency with other hash values, this value should be formatted as an uppercase hash. + examples: ["9E393D93138888D288266C2D915214D1D1CCEB2A"] + - id: client.hash.sha256 + type: string + stability: experimental + brief: > + Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the client. + For consistency with other hash values, this value should be formatted as an uppercase hash. + examples: + ["0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0"] + - id: client.issuer + type: string + stability: experimental + brief: "Distinguished name of [subject](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.6) of the issuer of the x.509 certificate presented by the client." + examples: + ["CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com"] + - id: client.ja3 + type: string + stability: experimental + brief: "A hash that identifies clients based on how they perform an SSL/TLS handshake." + examples: ["d4e5b18d6b55c71272893221c96ba240"] + - id: client.not_after + type: string + stability: experimental + brief: "Date/Time indicating when client certificate is no longer considered valid." + examples: ["2021-01-01T00:00:00.000Z"] + - id: client.not_before + type: string + stability: experimental + brief: "Date/Time indicating when client certificate is first considered valid." + examples: ["1970-01-01T00:00:00.000Z"] + - id: client.server_name + type: string + stability: experimental + brief: "Also called an SNI, this tells the server which hostname to which the client is attempting to connect to." + examples: ["opentelemetry.io"] + - id: client.subject + type: string + stability: experimental + brief: "Distinguished name of subject of the x.509 certificate presented by the client." + examples: ["CN=myclient, OU=Documentation Team, DC=example, DC=com"] + - id: client.supported_ciphers + type: string[] + stability: experimental + brief: Array of ciphers offered by the client during the client hello. + examples: + [ + '"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", "..."', + ] + - id: curve + brief: "String indicating the curve used for the given cipher, when applicable" + type: string + stability: experimental + examples: ["secp256r1"] + - id: established + brief: "Boolean flag indicating if the TLS negotiation was successful and transitioned to an encrypted tunnel." + type: boolean + stability: experimental + examples: [true] + - id: next_protocol + brief: > + String indicating the protocol being tunneled. + Per the values in the [IANA registry](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids), + this string should be lower case. + type: string + stability: experimental + examples: ["http/1.1"] + - id: protocol.name + brief: > + Normalized lowercase protocol name parsed from original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) + type: + allow_custom_values: true + members: + - id: ssl + value: ssl + stability: experimental + - id: tls + value: tls + stability: experimental + stability: experimental + - id: protocol.version + brief: > + Numeric part of the version parsed from the original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) + type: string + stability: experimental + examples: ["1.2", "3"] + - id: resumed + brief: "Boolean flag indicating if this TLS connection was resumed from an existing TLS negotiation." + type: boolean + stability: experimental + examples: [true] + - id: server.certificate + type: string + stability: experimental + brief: > + PEM-encoded stand-alone certificate offered by the server. This is usually mutually-exclusive of `server.certificate_chain` since this value also exists in that list. + examples: ["MII..."] + - id: server.certificate_chain + type: string[] + stability: experimental + brief: > + Array of PEM-encoded certificates that make up the certificate chain offered by the server. + This is usually mutually-exclusive of `server.certificate` since that value should be the first certificate in the chain. + examples: ["MII...", "MI..."] + - id: server.hash.md5 + type: string + stability: experimental + brief: > + Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the server. + For consistency with other hash values, this value should be formatted as an uppercase hash. + examples: ["0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC"] + - id: server.hash.sha1 + type: string + stability: experimental + brief: > + Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the server. + For consistency with other hash values, this value should be formatted as an uppercase hash. + examples: ["9E393D93138888D288266C2D915214D1D1CCEB2A"] + - id: server.hash.sha256 + type: string + stability: experimental + brief: > + Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the server. + For consistency with other hash values, this value should be formatted as an uppercase hash. + examples: + ["0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0"] + - id: server.issuer + type: string + stability: experimental + brief: "Distinguished name of [subject](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.6) of the issuer of the x.509 certificate presented by the client." + examples: + ["CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com"] + - id: server.ja3s + type: string + stability: experimental + brief: "A hash that identifies servers based on how they perform an SSL/TLS handshake." + examples: ["d4e5b18d6b55c71272893221c96ba240"] + - id: server.not_after + type: string + stability: experimental + brief: "Date/Time indicating when server certificate is no longer considered valid." + examples: ["2021-01-01T00:00:00.000Z"] + - id: server.not_before + type: string + stability: experimental + brief: "Date/Time indicating when server certificate is first considered valid." + examples: ["1970-01-01T00:00:00.000Z"] + - id: server.subject + type: string + stability: experimental + brief: "Distinguished name of subject of the x.509 certificate presented by the server." + examples: ["CN=myserver, OU=Documentation Team, DC=example, DC=com"] diff --git a/model/registry/url.yaml b/model/registry/url.yaml new file mode 100644 index 0000000000..e0bd823f1c --- /dev/null +++ b/model/registry/url.yaml @@ -0,0 +1,116 @@ +groups: + - id: registry.url + brief: Attributes describing URL. + type: attribute_group + prefix: url + attributes: + - id: domain + type: string + stability: experimental + brief: > + Domain extracted from the `url.full`, such as "opentelemetry.io". + note: > + In some cases a URL may refer to an IP and/or port directly, + without a domain name. In this case, the IP address would go to the domain field. + If the URL contains a [literal IPv6 address](https://www.rfc-editor.org/rfc/rfc2732#section-2) + enclosed by `[` and `]`, the `[` and `]` characters should also be captured in the domain field. + examples: ["www.foo.bar", "opentelemetry.io", "3.12.167.2", "[1080:0:0:0:8:800:200C:417A]"] + - id: extension + type: string + stability: experimental + brief: > + The file extension extracted from the `url.full`, excluding the leading dot. + note: > + The file extension is only set if it exists, as not every url has a file extension. + When the file name has multiple extensions `example.tar.gz`, only the last one should be captured `gz`, not `tar.gz`. + examples: [ "png", "gz" ] + - id: fragment + stability: stable + type: string + brief: > + The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component + examples: ["SemConv"] + - id: full + stability: stable + type: string + brief: Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) + note: > + For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment + is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. + + `url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. + In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. + + `url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). + Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. + examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv', '//localhost'] + - id: original + type: string + stability: experimental + brief: > + Unmodified original URL as seen in the event source. + note: > + In network monitoring, the observed URL may be a full URL, whereas in access logs, the URL is often + just represented as a path. This field is meant to represent the URL as it was observed, complete or not. + + `url.original` might contain credentials passed via URL in form of `https://username:password@www.example.com/`. + In such case password and username SHOULD NOT be redacted and attribute's value SHOULD remain the same. + examples: ["https://www.foo.bar/search?q=OpenTelemetry#SemConv", "search?q=OpenTelemetry"] + - id: path + stability: stable + type: string + brief: > + The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component + examples: ["/search"] + note: > + Sensitive content provided in `url.path` SHOULD be scrubbed when instrumentations can identify it. + - id: port + type: int + stability: experimental + brief: > + Port extracted from the `url.full` + examples: [443] + - id: query + stability: stable + type: string + brief: > + The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component + examples: ["q=OpenTelemetry"] + note: > + Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it. + - id: registered_domain + type: string + stability: experimental + brief: > + The highest registered url domain, stripped of the subdomain. + examples: ["example.com", "foo.co.uk"] + note: > + This value can be determined precisely with the [public suffix list](http://publicsuffix.org). + For example, the registered domain for `foo.example.com` is `example.com`. + Trying to approximate this by simply taking the last two labels will not work well for TLDs such as `co.uk`. + - id: scheme + stability: stable + type: string + brief: > + The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. + examples: ["https", "ftp", "telnet"] + - id: subdomain + type: string + stability: experimental + brief: > + The subdomain portion of a fully qualified domain name includes all of the names except the host name + under the registered_domain. In a partially qualified domain, or if the qualification level of the + full name cannot be determined, subdomain contains all of the names below the registered domain. + examples: ["east", "sub2.sub1"] + note: > + The subdomain portion of `www.east.mydomain.co.uk` is `east`. If the domain has multiple levels of subdomain, + such as `sub2.sub1.example.com`, the subdomain field should contain `sub2.sub1`, with no trailing period. + - id: top_level_domain + type: string + stability: experimental + brief: > + The effective top level domain (eTLD), also known as the domain suffix, is the last part of the domain name. + For example, the top level domain for example.com is `com`. + examples: ["com", "co.uk"] + note: > + This value can be determined precisely with the [public suffix list](http://publicsuffix.org). diff --git a/model/registry/user-agent.yaml b/model/registry/user-agent.yaml new file mode 100644 index 0000000000..5503454d22 --- /dev/null +++ b/model/registry/user-agent.yaml @@ -0,0 +1,36 @@ +groups: + - id: registry.user_agent + prefix: user_agent + type: attribute_group + brief: "Describes user-agent attributes." + attributes: + - id: original + stability: stable + type: string + brief: > + Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. + examples: ['CERN-LineMode/2.15 libwww/2.17b3', + 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1', + 'YourApp/1.0.0 grpc-java-okhttp/1.27.2'] + - id: name + type: string + stability: experimental + brief: > + Name of the user-agent extracted from original. Usually refers to the browser's name. + examples: ['Safari', 'YourApp'] + note: > + [Example](https://www.whatsmyua.info) of extracting browser's name from original string. In the case of using + a user-agent for non-browser products, such as microservices with multiple names/versions inside the + `user_agent.original`, the most significant name SHOULD be selected. In such a scenario it should align with + `user_agent.version` + - id: version + type: string + stability: experimental + brief: > + Version of the user-agent extracted from original. Usually refers to the browser's version + examples: ['14.1.2', '1.0.0'] + note: > + [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of + using a user-agent for non-browser products, such as microservices with multiple names/versions inside the + `user_agent.original`, the most significant version SHOULD be selected. In such a scenario it should align + with `user_agent.name` diff --git a/model/registry/webengine.yaml b/model/registry/webengine.yaml new file mode 100644 index 0000000000..a1579b7d24 --- /dev/null +++ b/model/registry/webengine.yaml @@ -0,0 +1,25 @@ +groups: + - id: registry.webengine + prefix: webengine + type: attribute_group + brief: > + This document defines the attributes used to describe the packaged software running the application code. + attributes: + - id: name + type: string + stability: experimental + brief: > + The name of the web engine. + examples: ['WildFly'] + - id: version + type: string + stability: experimental + brief: > + The version of the web engine. + examples: ['21.0.0'] + - id: description + type: string + stability: experimental + brief: > + Additional description of the web engine (e.g. detailed version and edition information). + examples: ['WildFly Full 21.0.0.Final (WildFly Core 13.0.1.Final) - 2.2.2.Final'] diff --git a/model/resource/android.yaml b/model/resource/android.yaml new file mode 100644 index 0000000000..0f2b756eb9 --- /dev/null +++ b/model/resource/android.yaml @@ -0,0 +1,8 @@ +groups: + - id: android + prefix: android + type: resource + brief: > + The Android platform on which the Android application is running. + attributes: + - ref: android.os.api_level diff --git a/model/resource/browser.yaml b/model/resource/browser.yaml index 56830c1dde..0ec1a6e3aa 100644 --- a/model/resource/browser.yaml +++ b/model/resource/browser.yaml @@ -7,46 +7,10 @@ groups: The `browser.*` attributes MUST be used only for resources that represent applications running in a web browser (regardless of whether running on a mobile or desktop device). attributes: - - id: brands - type: string[] - brief: 'Array of brand name and version separated by a space' - note: > - This value is intended to be taken from the - [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) - (`navigator.userAgentData.brands`). - examples: [" Not A;Brand 99", "Chromium 99", "Chrome 99"] - - id: platform - type: string - brief: 'The platform on which the browser is running' - note: > - This value is intended to be taken from the - [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) - (`navigator.userAgentData.platform`). If unavailable, the legacy - `navigator.platform` API SHOULD NOT be used instead and this attribute - SHOULD be left unset in order for the values to be consistent. - - The list of possible values is defined in the - [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). - Note that some (but not all) of these values can overlap with values - in the [`os.type` and `os.name` attributes](./os.md). - However, for consistency, the values in the `browser.platform` attribute - should capture the exact value that the user agent provides. - examples: ['Windows', 'macOS', 'Android'] - - id: mobile - type: boolean - brief: 'A boolean that is true if the browser is running on a mobile device' - note: > - This value is intended to be taken from the - [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) - (`navigator.userAgentData.mobile`). If unavailable, this attribute - SHOULD be left unset. - - id: language - type: string - brief: 'Preferred language of the user using the browser' - note: > - This value is intended to be taken from the Navigator API - `navigator.language`. - examples: ["en", "en-US", "fr", "fr-FR"] + - ref: browser.brands + - ref: browser.platform + - ref: browser.mobile + - ref: browser.language - ref: user_agent.original brief: 'Full user-agent string provided by the browser' note: > diff --git a/model/resource/cloud.yaml b/model/resource/cloud.yaml index c24e474855..4699f84842 100644 --- a/model/resource/cloud.yaml +++ b/model/resource/cloud.yaml @@ -5,175 +5,9 @@ groups: brief: > A cloud environment (e.g. GCP, Azure, AWS) attributes: - - id: provider - type: - allow_custom_values: true - members: - - id: 'alibaba_cloud' - value: 'alibaba_cloud' - brief: 'Alibaba Cloud' - - id: 'aws' - value: 'aws' - brief: 'Amazon Web Services' - - id: 'azure' - value: 'azure' - brief: 'Microsoft Azure' - - id: 'gcp' - value: 'gcp' - brief: 'Google Cloud Platform' - - id: 'heroku' - value: 'heroku' - brief: 'Heroku Platform as a Service' - - id: 'ibm_cloud' - value: 'ibm_cloud' - brief: 'IBM Cloud' - - id: 'tencent_cloud' - value: 'tencent_cloud' - brief: 'Tencent Cloud' - - brief: > - Name of the cloud provider. - - id: account.id - type: string - brief: > - The cloud account ID the resource is assigned to. - examples: ['111111111111', 'opentelemetry'] - - id: region - type: string - brief: > - The geographical region the resource is running. - note: > - Refer to your provider's docs to see the available regions, for example - [Alibaba Cloud regions](https://www.alibabacloud.com/help/doc-detail/40654.htm), - [AWS regions](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/), - [Azure regions](https://azure.microsoft.com/en-us/global-infrastructure/geographies/), - [Google Cloud regions](https://cloud.google.com/about/locations), - or [Tencent Cloud regions](https://www.tencentcloud.com/document/product/213/6091). - examples: ['us-central1', 'us-east-1'] - - id: resource_id - type: string - brief: > - Cloud provider-specific native identifier of the monitored cloud resource - (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, - a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, - a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) - note: | - On some cloud providers, it may not be possible to determine the full ID at startup, - so it may be necessary to set `cloud.resource_id` as a span attribute instead. - - The exact value to use for `cloud.resource_id` depends on the cloud provider. - The following well-known definitions MUST be used if you set this attribute and they apply: - - * **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). - Take care not to use the "invoked ARN" directly but replace any - [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) - with the resolved function version, as the same runtime instance may be invokable with - multiple different aliases. - * **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) - * **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id) of the invoked function, - *not* the function app, having the form - `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/`. - This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share - a TracerProvider. - examples: - - 'arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function' - - '//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID' - - '/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/' - - id: availability_zone - type: string - brief: > - Cloud regions often have multiple, isolated locations known as zones - to increase availability. Availability zone represents the - zone where the resource is running. - note: > - Availability zones are called "zones" on Alibaba Cloud and Google Cloud. - examples: ['us-east-1c'] - - id: platform - type: - allow_custom_values: true - members: - - id: alibaba_cloud_ecs - value: 'alibaba_cloud_ecs' - brief: Alibaba Cloud Elastic Compute Service - - id: alibaba_cloud_fc - value: 'alibaba_cloud_fc' - brief: Alibaba Cloud Function Compute - - id: alibaba_cloud_openshift - value: 'alibaba_cloud_openshift' - brief: Red Hat OpenShift on Alibaba Cloud - - id: aws_ec2 - value: 'aws_ec2' - brief: AWS Elastic Compute Cloud - - id: aws_ecs - value: 'aws_ecs' - brief: AWS Elastic Container Service - - id: aws_eks - value: 'aws_eks' - brief: AWS Elastic Kubernetes Service - - id: aws_lambda - value: 'aws_lambda' - brief: AWS Lambda - - id: aws_elastic_beanstalk - value: 'aws_elastic_beanstalk' - brief: AWS Elastic Beanstalk - - id: aws_app_runner - value: 'aws_app_runner' - brief: AWS App Runner - - id: aws_openshift - value: 'aws_openshift' - brief: Red Hat OpenShift on AWS (ROSA) - - id: azure_vm - value: 'azure_vm' - brief: Azure Virtual Machines - - id: azure_container_instances - value: 'azure_container_instances' - brief: Azure Container Instances - - id: azure_aks - value: 'azure_aks' - brief: Azure Kubernetes Service - - id: azure_functions - value: 'azure_functions' - brief: Azure Functions - - id: azure_app_service - value: 'azure_app_service' - brief: Azure App Service - - id: azure_openshift - value: 'azure_openshift' - brief: Azure Red Hat OpenShift - - id: gcp_bare_metal_solution - value: 'gcp_bare_metal_solution' - brief: Google Bare Metal Solution (BMS) - - id: gcp_compute_engine - value: 'gcp_compute_engine' - brief: Google Cloud Compute Engine (GCE) - - id: gcp_cloud_run - value: 'gcp_cloud_run' - brief: Google Cloud Run - - id: gcp_kubernetes_engine - value: 'gcp_kubernetes_engine' - brief: Google Cloud Kubernetes Engine (GKE) - - id: gcp_cloud_functions - value: 'gcp_cloud_functions' - brief: Google Cloud Functions (GCF) - - id: gcp_app_engine - value: 'gcp_app_engine' - brief: Google Cloud App Engine (GAE) - - id: gcp_openshift - value: 'gcp_openshift' - brief: Red Hat OpenShift on Google Cloud - - id: ibm_cloud_openshift - value: 'ibm_cloud_openshift' - brief: Red Hat OpenShift on IBM Cloud - - id: tencent_cloud_cvm - value: 'tencent_cloud_cvm' - brief: Tencent Cloud Cloud Virtual Machine (CVM) - - id: tencent_cloud_eks - value: 'tencent_cloud_eks' - brief: Tencent Cloud Elastic Kubernetes Service (EKS) - - id: tencent_cloud_scf - value: 'tencent_cloud_scf' - brief: Tencent Cloud Serverless Cloud Function (SCF) - brief: > - The cloud platform in use. - note: > - The prefix of the service SHOULD match the one specified in `cloud.provider`. + - ref: cloud.provider + - ref: cloud.account.id + - ref: cloud.region + - ref: cloud.resource_id + - ref: cloud.availability_zone + - ref: cloud.platform diff --git a/model/resource/cloud_provider/aws/ecs.yaml b/model/resource/cloud_provider/aws/ecs.yaml index 2c6b8c9ba5..53c998c575 100644 --- a/model/resource/cloud_provider/aws/ecs.yaml +++ b/model/resource/cloud_provider/aws/ecs.yaml @@ -1,42 +1,22 @@ groups: - id: aws.ecs - prefix: aws.ecs type: resource brief: > Resources used by AWS Elastic Container Service (ECS). attributes: - - id: container.arn - type: string - brief: > - The Amazon Resource Name (ARN) of an [ECS container instance](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html). - examples: ['arn:aws:ecs:us-west-1:123456789123:container/32624152-9086-4f0e-acae-1a75b14fe4d9'] - - id: cluster.arn - type: string - brief: > - The ARN of an [ECS cluster](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/clusters.html). - examples: ['arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster'] - - id: launchtype - type: - allow_custom_values: false - members: - - id: ec2 - value: "ec2" - - id: fargate - value: "fargate" - brief: > - The [launch type](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_types.html) for an ECS task. - - id: task.arn - type: string - brief: > - The ARN of an [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html). - examples: ['arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b'] - - id: task.family - type: string - brief: > - The task definition family this task definition is a member of. - examples: ['opentelemetry-family'] - - id: task.revision - type: string - brief: > - The revision for this task definition. - examples: ["8", "26"] + - ref: aws.ecs.container.arn + requirement_level: recommended + - ref: aws.ecs.cluster.arn + requirement_level: recommended + - ref: aws.ecs.launchtype + requirement_level: recommended + - ref: aws.ecs.task.arn + requirement_level: recommended + - ref: aws.ecs.task.family + requirement_level: recommended + - ref: aws.ecs.task.id + requirement_level: + conditionally_required: If and only if `task.arn` is populated. + examples: [ '10838bed-421f-43ef-870a-f43feacbbb5b', '23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd' ] + - ref: aws.ecs.task.revision + requirement_level: recommended diff --git a/model/resource/cloud_provider/aws/eks.yaml b/model/resource/cloud_provider/aws/eks.yaml index 2c897253ee..a25713cdfd 100644 --- a/model/resource/cloud_provider/aws/eks.yaml +++ b/model/resource/cloud_provider/aws/eks.yaml @@ -1,12 +1,8 @@ groups: - id: aws.eks - prefix: aws.eks type: resource brief: > Resources used by AWS Elastic Kubernetes Service (EKS). attributes: - - id: cluster.arn - type: string - brief: > - The ARN of an EKS cluster. - examples: ['arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster'] + - ref: aws.eks.cluster.arn + requirement_level: recommended diff --git a/model/resource/cloud_provider/aws/logs.yaml b/model/resource/cloud_provider/aws/logs.yaml index 8a433629bb..ffd5feb3d4 100644 --- a/model/resource/cloud_provider/aws/logs.yaml +++ b/model/resource/cloud_provider/aws/logs.yaml @@ -1,39 +1,14 @@ groups: - id: aws.log - prefix: aws.log type: resource brief: > Resources specific to Amazon Web Services. attributes: - - id: group.names - type: string[] - brief: > - The name(s) of the AWS log group(s) an application is writing to. - examples: ['/aws/lambda/my-function', 'opentelemetry-service'] - note: > - Multiple log groups must be supported for cases like multi-container applications, - where a single application has sidecar containers, and each write to their own log - group. - - id: group.arns - type: string[] - brief: > - The Amazon Resource Name(s) (ARN) of the AWS log group(s). - examples: ['arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:*'] - note: > - See the - [log group ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). - - id: stream.names - type: string[] - brief: > - The name(s) of the AWS log stream(s) an application is writing to. - examples: ['logs/main/10838bed-421f-43ef-870a-f43feacbbb5b'] - - id: stream.arns - type: string[] - brief: > - The ARN(s) of the AWS log stream(s). - examples: ['arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:log-stream:logs/main/10838bed-421f-43ef-870a-f43feacbbb5b'] - note: > - See the - [log stream ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). - One log group can contain several log streams, so these ARNs necessarily identify both a log - group and a log stream. + - ref: aws.log.group.names + requirement_level: recommended + - ref: aws.log.group.arns + requirement_level: recommended + - ref: aws.log.stream.names + requirement_level: recommended + - ref: aws.log.stream.arns + requirement_level: recommended diff --git a/model/resource/cloud_provider/gcp/cloud_run.yaml b/model/resource/cloud_provider/gcp/cloud_run.yaml index e4da8f5929..3f05837747 100644 --- a/model/resource/cloud_provider/gcp/cloud_run.yaml +++ b/model/resource/cloud_provider/gcp/cloud_run.yaml @@ -1,23 +1,10 @@ groups: - id: gcp.cloud_run - prefix: gcp.cloud_run type: resource brief: > Resource used by Google Cloud Run. attributes: - - id: job.execution - type: string - brief: > - The name of the Cloud Run - [execution](https://cloud.google.com/run/docs/managing/job-executions) - being run for the Job, as set by the - [`CLOUD_RUN_EXECUTION`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) - environment variable. - examples: ['job-name-xxxx', 'sample-job-mdw84'] - - id: job.task_index - type: int - brief: > - The index for a task within an execution as provided by the - [`CLOUD_RUN_TASK_INDEX`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) - environment variable. - examples: [0, 1] + - ref: gcp.cloud_run.job.execution + requirement_level: recommended + - ref: gcp.cloud_run.job.task_index + requirement_level: recommended diff --git a/model/resource/cloud_provider/gcp/gce.yaml b/model/resource/cloud_provider/gcp/gce.yaml index 879d0ea388..d29684b2a3 100644 --- a/model/resource/cloud_provider/gcp/gce.yaml +++ b/model/resource/cloud_provider/gcp/gce.yaml @@ -1,22 +1,10 @@ groups: - id: gcp.gce - prefix: gcp.gce type: resource brief: > Resources used by Google Compute Engine (GCE). attributes: - - id: instance.name - type: string - brief: > - The instance name of a GCE instance. This is the value - provided by `host.name`, the visible name of the instance in - the Cloud Console UI, and the prefix for the default - hostname of the instance as defined by the [default internal - DNS - name](https://cloud.google.com/compute/docs/internal-dns#instance-fully-qualified-domain-names). - examples: ['instance-1', 'my-vm-name'] - - id: instance.hostname - type: string - brief: > - The hostname of a GCE instance. This is the full value of the default or [custom hostname](https://cloud.google.com/compute/docs/instances/custom-hostname-vm). - examples: ['my-host1234.example.com', 'sample-vm.us-west1-b.c.my-project.internal'] + - ref: gcp.gce.instance.name + requirement_level: recommended + - ref: gcp.gce.instance.hostname + requirement_level: recommended diff --git a/model/resource/cloud_provider/heroku.yaml b/model/resource/cloud_provider/heroku.yaml index e73eddc1e7..f609f473e4 100644 --- a/model/resource/cloud_provider/heroku.yaml +++ b/model/resource/cloud_provider/heroku.yaml @@ -1,25 +1,12 @@ groups: - id: heroku - prefix: heroku type: resource brief: > Heroku dyno metadata attributes: - - id: release.creation_timestamp - type: string - brief: > - Time and date the release was created - examples: [ '2022-10-23T18:00:42Z' ] + - ref: heroku.release.creation_timestamp requirement_level: opt_in - - id: release.commit - type: string - brief: > - Commit hash for the current release - examples: [ 'e6134959463efd8966b20e75b913cafe3f5ec' ] + - ref: heroku.release.commit requirement_level: opt_in - - id: app.id - type: string - brief: > - Unique identifier for the application - examples: [ '2daa2797-e42b-4624-9322-ec3f968df4da' ] + - ref: heroku.app.id requirement_level: opt_in diff --git a/model/resource/container.yaml b/model/resource/container.yaml index f3f52c7cfa..c0034ca7ca 100644 --- a/model/resource/container.yaml +++ b/model/resource/container.yaml @@ -5,64 +5,18 @@ groups: brief: > A container instance. attributes: - - id: name - type: string - brief: > - Container name used by container runtime. - examples: ['opentelemetry-autoconf'] - - id: id - type: string - brief: > - 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. - examples: ['a3bf90e006b2'] - - id: runtime - type: string - brief: > - The container runtime managing this container. - examples: ['docker', 'containerd', 'rkt'] - - id: image.name - type: string - brief: > - Name of the image the container was built on. - examples: ['gcr.io/opentelemetry/operator'] - - id: image.tag - type: string - brief: > - Container image tag. - examples: ['0.1'] - - id: image.id - type: string - brief: > - Runtime specific image identifier. Usually a hash algorithm followed by a UUID. - note: > - Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker - container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) - endpoint. - - K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io - /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`. - - OCI defines a digest of manifest. - examples: ['sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f'] - - id: command - type: string + - ref: container.name + - ref: container.id + - ref: container.runtime + - ref: container.image.name + - ref: container.image.tags + - ref: container.image.id + - ref: container.image.repo_digests + - ref: container.command requirement_level: opt_in - note: > - If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. - brief: > - The command used to run the container (i.e. the command name). - examples: [ 'otelcontribcol' ] - - id: command_line - type: string + - ref: container.command_line requirement_level: opt_in - brief: > - The full command run by the container as a single string representing the full command. [2] - examples: [ 'otelcontribcol --config config.yaml' ] - - id: command_args - type: string[] + - ref: container.command_args requirement_level: opt_in - brief: > - All the command arguments (including the command/executable itself) run by the container. [2] - examples: [ 'otelcontribcol, --config, config.yaml' ] + - ref: container.label + - ref: oci.manifest.digest diff --git a/model/resource/deployment_environment.yaml b/model/resource/deployment_environment.yaml index 336cabeced..c9a54bc7fa 100644 --- a/model/resource/deployment_environment.yaml +++ b/model/resource/deployment_environment.yaml @@ -1,13 +1,8 @@ groups: - id: deployment - prefix: deployment type: resource brief: > The software deployment. attributes: - - id: environment - type: string - brief: > - Name of the [deployment environment](https://en.wikipedia.org/wiki/Deployment_environment) - (aka deployment tier). - examples: ['staging', 'production'] + - ref: deployment.environment + requirement_level: recommended diff --git a/model/resource/device.yaml b/model/resource/device.yaml index 3df0a4d6a8..8fab02a8e4 100644 --- a/model/resource/device.yaml +++ b/model/resource/device.yaml @@ -5,37 +5,7 @@ groups: brief: > The device on which the process represented by this resource is running. attributes: - - id: id - type: string - brief: 'A unique identifier representing the device' - note: > - The device identifier MUST only be defined using the values outlined below. This value is not an advertising - identifier and MUST NOT be used as such. - On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). - On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique - UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) - on best practices and exact implementation details. - Caution should be taken when storing personal data or anything which can identify a user. GDPR and - data protection laws may apply, ensure you do your own due diligence. - examples: ['2ab2916d-a51f-4ac8-80ee-45ac31a28092'] - - id: model.identifier - type: string - brief: 'The model identifier for the device' - note: > - It's recommended this value represents a machine readable version of - the model identifier rather than the market or consumer-friendly name - of the device. - examples: ['iPhone3,4', 'SM-G920F'] - - id: model.name - type: string - brief: 'The marketing name for the device model' - note: > - It's recommended this value represents a human readable version of the - device model rather than a machine readable alternative. - examples: ['iPhone 6s Plus', 'Samsung Galaxy S6'] - - id: manufacturer - type: string - brief: 'The name of the device manufacturer' - note: > - The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`. - examples: ['Apple', 'Samsung'] + - ref: device.id + - ref: device.manufacturer + - ref: device.model.identifier + - ref: device.model.name diff --git a/model/resource/faas.yaml b/model/resource/faas.yaml index 7f1a02e0e0..ab028c89bb 100644 --- a/model/resource/faas.yaml +++ b/model/resource/faas.yaml @@ -5,59 +5,9 @@ groups: brief: > A serverless instance. attributes: - - id: name - type: string + - ref: faas.name requirement_level: required - brief: > - The name of the single function that this runtime instance executes. - note: | - This is the name of the function as configured/deployed on the FaaS - platform and is usually different from the name of the callback - function (which may be stored in the - [`code.namespace`/`code.function`](/docs/general/attributes.md#source-code-attributes) - span attributes). - - For some cloud providers, the above definition is ambiguous. The following - definition of function name MUST be used for this attribute - (and consequently the span name) for the listed cloud providers/products: - - * **Azure:** The full name `/`, i.e., function app name - followed by a forward slash followed by the function name (this form - can also be seen in the resource JSON for the function). - This means that a span attribute MUST be used, as an Azure function - app can host multiple functions that would usually share - a TracerProvider (see also the `cloud.resource_id` attribute). - examples: ['my-function', 'myazurefunctionapp/some-function-name'] - - id: version - type: string - brief: The immutable version of the function being executed. - note: | - Depending on the cloud provider and platform, use: - - * **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) - (an integer represented as a decimal string). - * **Google Cloud Run (Services):** The [revision](https://cloud.google.com/run/docs/managing/revisions) - (i.e., the function name plus the revision suffix). - * **Google Cloud Functions:** The value of the - [`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically). - * **Azure Functions:** Not applicable. Do not set this attribute. - examples: ['26', 'pinkfroid-00002'] - - id: instance - type: string - brief: > - The execution environment ID as a string, that will be potentially reused - for other invocations to the same function/function version. - note: > - * **AWS Lambda:** Use the (full) log stream name. - examples: ['2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de'] - - id: max_memory - type: int - brief: > - The amount of memory available to the serverless function converted to Bytes. - note: > - It's recommended to set this attribute since e.g. too little memory can easily - stop a Java AWS Lambda function from working correctly. - On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` - provides this information (which must be multiplied by 1,048,576). - examples: 134217728 + - ref: faas.version + - ref: faas.instance + - ref: faas.max_memory - ref: cloud.resource_id diff --git a/model/resource/host.yaml b/model/resource/host.yaml index 457aa1c8ae..b90b90dcf7 100644 --- a/model/resource/host.yaml +++ b/model/resource/host.yaml @@ -5,68 +5,33 @@ groups: brief: > A host is defined as a computing instance. For example, physical servers, virtual machines, switches or disk array. attributes: - - id: id - type: string - brief: > - Unique host ID. For Cloud, this must be the instance_id assigned by the cloud provider. - For non-containerized systems, this should be the `machine-id`. See the table below for - the sources to use to determine the `machine-id` based on operating system. - examples: ['fdbf79e8af94cb7f9e8df36789187052'] - - id: name - type: string - brief: > - Name of the host. On Unix systems, it may contain what the hostname - command returns, or the fully qualified hostname, or another name - specified by the user. - examples: ['opentelemetry-test'] - - id: type - type: string - brief: > - Type of host. For Cloud, this must be the machine type. - examples: ['n1-standard-1'] - - id: arch - type: - allow_custom_values: true - members: - - id: amd64 - value: 'amd64' - brief: "AMD64" - - id: arm32 - value: 'arm32' - brief: "ARM32" - - id: arm64 - value: 'arm64' - brief: "ARM64" - - id: ia64 - value: 'ia64' - brief: "Itanium" - - id: ppc32 - value: 'ppc32' - brief: "32-bit PowerPC" - - id: ppc64 - value: 'ppc64' - brief: "64-bit PowerPC" - - id: s390x - value: 's390x' - brief: "IBM z/Architecture" - - id: x86 - value: 'x86' - brief: "32-bit x86" - brief: > - The CPU architecture the host system is running on. - - id: image.name - type: string - brief: > - Name of the VM image or OS install the host was instantiated from. - examples: ['infra-ami-eks-worker-node-7d4ec78312', 'CentOS-8-x86_64-1905'] - - id: image.id - type: string - brief: > - VM image ID or host OS image ID. For Cloud, this value is from the provider. - examples: ['ami-07b06b442921831e5'] - - id: image.version - type: string - brief: > - The version string of the VM image or host OS as defined in - [Version Attributes](README.md#version-attributes). - examples: ['0.1'] + - ref: host.id + - ref: host.name + - ref: host.type + - ref: host.arch + - ref: host.image.name + - ref: host.image.id + - ref: host.image.version + - ref: host.ip + requirement_level: opt_in + - ref: host.mac + requirement_level: opt_in + + - id: host.cpu + prefix: host.cpu + type: resource + brief: > + A host's CPU information + attributes: + - ref: host.cpu.vendor.id + requirement_level: opt_in + - ref: host.cpu.family + requirement_level: opt_in + - ref: host.cpu.model.id + requirement_level: opt_in + - ref: host.cpu.model.name + requirement_level: opt_in + - ref: host.cpu.stepping + requirement_level: opt_in + - ref: host.cpu.cache.l2.size + requirement_level: opt_in diff --git a/model/resource/k8s.yaml b/model/resource/k8s.yaml index 32a9716dbe..d94425e007 100644 --- a/model/resource/k8s.yaml +++ b/model/resource/k8s.yaml @@ -5,40 +5,8 @@ groups: brief: > A Kubernetes Cluster. attributes: - - id: name - type: string - brief: > - The name of the cluster. - examples: ['opentelemetry-cluster'] - - id: uid - type: string - brief: > - A pseudo-ID for the cluster, set to the UID of the `kube-system` - namespace. - note: | - K8s does not have support for obtaining a cluster ID. If this is ever - added, we will recommend collecting the `k8s.cluster.uid` through the - official APIs. In the meantime, we are able to use the `uid` of the - `kube-system` namespace as a proxy for cluster ID. Read on for the - rationale. - - Every object created in a K8s cluster is assigned a distinct UID. The - `kube-system` namespace is used by Kubernetes itself and will exist - for the lifetime of the cluster. Using the `uid` of the `kube-system` - namespace is a reasonable proxy for the K8s ClusterID as it will only - change if the cluster is rebuilt. Furthermore, Kubernetes UIDs are - UUIDs as standardized by - [ISO/IEC 9834-8 and ITU-T X.667](https://www.itu.int/ITU-T/studygroups/com17/oid.html). - Which states: - - > If generated according to one of the mechanisms defined in Rec. - ITU-T X.667 | ISO/IEC 9834-8, a UUID is either guaranteed to be - different from all other UUIDs generated before 3603 A.D., or is - extremely likely to be different (depending on the mechanism chosen). - - Therefore, UIDs between clusters should be extremely unlikely to - conflict. - examples: ['218fc5a9-a5f1-4b54-aa05-46717d0ab26d'] + - ref: k8s.cluster.name + - ref: k8s.cluster.uid - id: k8s.node prefix: k8s.node @@ -46,16 +14,8 @@ groups: brief: > A Kubernetes Node object. attributes: - - id: name - type: string - brief: > - The name of the Node. - examples: ['node-1'] - - id: uid - type: string - brief: > - The UID of the Node. - examples: ['1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2'] + - ref: k8s.node.name + - ref: k8s.node.uid - id: k8s.namespace prefix: k8s.namespace @@ -63,11 +23,7 @@ groups: brief: > A Kubernetes Namespace. attributes: - - id: name - type: string - brief: > - The name of the namespace that the pod is running in. - examples: ['default'] + - ref: k8s.namespace.name - id: k8s.pod prefix: k8s.pod @@ -75,16 +31,11 @@ groups: brief: > A Kubernetes Pod object. attributes: - - id: uid - type: string - brief: > - The UID of the Pod. - examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - - id: name - type: string - brief: > - The name of the Pod. - examples: ['opentelemetry-pod-autoconf'] + - ref: k8s.pod.uid + - ref: k8s.pod.name + - ref: k8s.pod.label + - ref: k8s.pod.annotation + requirement_level: opt_in - id: k8s.container prefix: k8s.container @@ -92,20 +43,9 @@ groups: brief: > A container in a [PodTemplate](https://kubernetes.io/docs/concepts/workloads/pods/#pod-templates). attributes: - - id: name - type: string - brief: > - The name of the Container from Pod specification, must be unique - within a Pod. Container runtime usually uses different globally unique - name (`container.name`). - examples: ['redis'] - - id: restart_count - type: int - brief: > - Number of times the container was restarted. This attribute can be - used to identify a particular container (running or stopped) within a - container spec. - examples: [0, 2] + - ref: k8s.container.name + - ref: k8s.container.restart_count + - ref: k8s.container.status.last_terminated_reason - id: k8s.replicaset prefix: k8s.replicaset @@ -113,16 +53,8 @@ groups: brief: > A Kubernetes ReplicaSet object. attributes: - - id: uid - type: string - brief: > - The UID of the ReplicaSet. - examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - - id: name - type: string - brief: > - The name of the ReplicaSet. - examples: ['opentelemetry'] + - ref: k8s.replicaset.uid + - ref: k8s.replicaset.name - id: k8s.deployment prefix: k8s.deployment @@ -130,16 +62,8 @@ groups: brief: > A Kubernetes Deployment object. attributes: - - id: uid - type: string - brief: > - The UID of the Deployment. - examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - - id: name - type: string - brief: > - The name of the Deployment. - examples: ['opentelemetry'] + - ref: k8s.deployment.uid + - ref: k8s.deployment.name - id: k8s.statefulset prefix: k8s.statefulset @@ -147,16 +71,8 @@ groups: brief: > A Kubernetes StatefulSet object. attributes: - - id: uid - type: string - brief: > - The UID of the StatefulSet. - examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - - id: name - type: string - brief: > - The name of the StatefulSet. - examples: ['opentelemetry'] + - ref: k8s.statefulset.uid + - ref: k8s.statefulset.name - id: k8s.daemonset prefix: k8s.daemonset @@ -164,16 +80,8 @@ groups: brief: > A Kubernetes DaemonSet object. attributes: - - id: uid - type: string - brief: > - The UID of the DaemonSet. - examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - - id: name - type: string - brief: > - The name of the DaemonSet. - examples: ['opentelemetry'] + - ref: k8s.daemonset.uid + - ref: k8s.daemonset.name - id: k8s.job prefix: k8s.job @@ -181,16 +89,8 @@ groups: brief: > A Kubernetes Job object. attributes: - - id: uid - type: string - brief: > - The UID of the Job. - examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - - id: name - type: string - brief: > - The name of the Job. - examples: ['opentelemetry'] + - ref: k8s.job.uid + - ref: k8s.job.name - id: k8s.cronjob prefix: k8s.cronjob @@ -198,13 +98,5 @@ groups: brief: > A Kubernetes CronJob object. attributes: - - id: uid - type: string - brief: > - The UID of the CronJob. - examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - - id: name - type: string - brief: > - The name of the CronJob. - examples: ['opentelemetry'] + - ref: k8s.cronjob.uid + - ref: k8s.cronjob.name diff --git a/model/resource/os.yaml b/model/resource/os.yaml index 083b88495e..772fdde3a0 100644 --- a/model/resource/os.yaml +++ b/model/resource/os.yaml @@ -8,58 +8,9 @@ groups: In case of virtualized environments, this is the operating system as it is observed by the process, i.e., the virtualized guest rather than the underlying host. attributes: - - id: type - type: - allow_custom_values: true - members: - - id: windows - value: 'windows' - brief: "Microsoft Windows" - - id: linux - value: 'linux' - brief: "Linux" - - id: darwin - value: 'darwin' - brief: "Apple Darwin" - - id: freebsd - value: 'freebsd' - brief: "FreeBSD" - - id: netbsd - value: 'netbsd' - brief: "NetBSD" - - id: openbsd - value: 'openbsd' - brief: "OpenBSD" - - id: dragonflybsd - value: 'dragonflybsd' - brief: "DragonFly BSD" - - id: hpux - value: 'hpux' - brief: "HP-UX (Hewlett Packard Unix)" - - id: aix - value: 'aix' - brief: "AIX (Advanced Interactive eXecutive)" - - id: solaris - value: 'solaris' - brief: "SunOS, Oracle Solaris" - - id: z_os - value: 'z_os' - brief: "IBM z/OS" + - ref: os.type requirement_level: required - brief: 'The operating system type.' - - id: description - type: string - brief: > - Human readable (not intended to be parsed) OS version information, - like e.g. reported by `ver` or `lsb_release -a` commands. - examples: ['Microsoft Windows [Version 10.0.18363.778]', 'Ubuntu 18.04.1 LTS'] - - id: name - type: string - brief: 'Human readable operating system name.' - examples: ['iOS', 'Android', 'Ubuntu'] - - id: version - type: string - brief: > - The version string of the operating system as defined in - [Version Attributes](/docs/resource/README.md#version-attributes). - examples: ['14.2.1', '18.04.1'] + - ref: os.description + - ref: os.name + - ref: os.version + - ref: os.build_id diff --git a/model/resource/process.yaml b/model/resource/process.yaml index d7d3b25b56..36becc7606 100644 --- a/model/resource/process.yaml +++ b/model/resource/process.yaml @@ -5,76 +5,24 @@ groups: brief: > An operating system process. attributes: - - id: pid - type: int - brief: > - Process identifier (PID). - examples: [1234] - - id: parent_pid - type: int - brief: > - Parent Process identifier (PID). - examples: [111] - - id: executable.name - type: string + - ref: process.pid + - ref: process.parent_pid + - ref: process.executable.name requirement_level: - conditionally_required: See alternative attributes below. - brief: > - The name of the process executable. On Linux based systems, can be set - to the `Name` in `proc/[pid]/status`. On Windows, can be set to the - base name of `GetProcessImageFileNameW`. - examples: ['otelcol'] - - id: executable.path - type: string + conditionally_required: See [Selecting process attributes](#selecting-process-attributes) for details. + - ref: process.executable.path requirement_level: - conditionally_required: See alternative attributes below. - brief: > - The full path to the process executable. On Linux based systems, can - be set to the target of `proc/[pid]/exe`. On Windows, can be set to the - result of `GetProcessImageFileNameW`. - examples: ['/usr/bin/cmd/otelcol'] - - id: command - type: string + conditionally_required: See [Selecting process attributes](#selecting-process-attributes) for details. + - ref: process.command requirement_level: - conditionally_required: See alternative attributes below. - brief: > - The command used to launch the process (i.e. the command name). On Linux - based systems, can be set to the zeroth string in `proc/[pid]/cmdline`. - On Windows, can be set to the first parameter extracted from `GetCommandLineW`. - examples: ['cmd/otelcol'] - - id: command_line - type: string + conditionally_required: See [Selecting process attributes](#selecting-process-attributes) for details. + - ref: process.command_line requirement_level: - conditionally_required: See alternative attributes below. - brief: > - The full command used to launch the process as a single string representing - the full command. On Windows, can be set to the result of `GetCommandLineW`. - Do not set this if you have to assemble it just for monitoring; use - `process.command_args` instead. - examples: ['C:\cmd\otecol --config="my directory\config.yaml"'] - - id: command_args - type: string[] + conditionally_required: See [Selecting process attributes](#selecting-process-attributes) for details. + - ref: process.command_args requirement_level: - conditionally_required: See alternative attributes below. - brief: > - All the command arguments (including the command/executable itself) as - received by the process. On Linux-based systems (and some other Unixoid - systems supporting procfs), can be set according to the list of - null-delimited strings extracted from `proc/[pid]/cmdline`. For libc-based - executables, this would be the full argv vector passed to `main`. - examples: ['cmd/otecol', '--config=config.yaml'] - - id: owner - type: string - brief: > - The username of the user that owns the process. - examples: 'root' - constraints: - - any_of: - - process.executable.name - - process.executable.path - - process.command - - process.command_line - - process.command_args + conditionally_required: See [Selecting process attributes](#selecting-process-attributes) for details. + - ref: process.owner - id: process.runtime prefix: process.runtime @@ -82,21 +30,6 @@ groups: brief: > The single (language) runtime instance which is monitored. attributes: - - id: name - type: string - brief: > - The name of the runtime of this process. For compiled native binaries, - this SHOULD be the name of the compiler. - examples: ['OpenJDK Runtime Environment'] - - id: version - type: string - brief: > - The version of the runtime of this process, as returned by the runtime - without modification. - examples: '14.0.2' - - id: description - type: string - brief: > - An additional description about the runtime of the process, for example - a specific vendor customization of the runtime environment. - examples: 'Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0' + - ref: process.runtime.name + - ref: process.runtime.version + - ref: process.runtime.description diff --git a/model/resource/service.yaml b/model/resource/service.yaml index e930b62194..6384246ae6 100644 --- a/model/resource/service.yaml +++ b/model/resource/service.yaml @@ -5,19 +5,6 @@ groups: brief: > A service instance. attributes: - - id: name - type: string + - ref: service.name requirement_level: required - brief: > - Logical name of the service. - note: > - MUST be the same for all instances of horizontally scaled services. - If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated - with [`process.executable.name`](process.md#process), e.g. `unknown_service:bash`. - If `process.executable.name` is not available, the value MUST be set to `unknown_service`. - examples: ["shoppingcart"] - - id: version - type: string - brief: > - The version string of the service API or implementation. The format is not defined by these conventions. - examples: ["2.0.0", "a01dbef8a"] + - ref: service.version diff --git a/model/resource/service_experimental.yaml b/model/resource/service_experimental.yaml index 43c869ee35..97a58f6f6e 100644 --- a/model/resource/service_experimental.yaml +++ b/model/resource/service_experimental.yaml @@ -5,33 +5,5 @@ groups: brief: > A service instance. attributes: - - id: namespace - type: string - brief: > - A namespace for `service.name`. - note: > - A string value having a meaning that helps to distinguish a group of services, - for example the team name that owns a group of services. - `service.name` is expected to be unique within the same namespace. - If `service.namespace` is not specified in the Resource then `service.name` - is expected to be unique for all services that have no explicit namespace defined - (so the empty/unspecified namespace is simply one more valid namespace). - Zero-length namespace string is assumed equal to unspecified namespace. - examples: ["Shop"] - - id: instance.id - type: string - brief: > - The string ID of the service instance. - note: > - MUST be unique for each instance of the same `service.namespace,service.name` pair - (in other words `service.namespace,service.name,service.instance.id` triplet MUST be globally unique). - The ID helps to distinguish instances of the same service that exist at the same time - (e.g. instances of a horizontally scaled service). It is preferable for the ID to be persistent - and stay the same for the lifetime of the service instance, however it is acceptable that - the ID is ephemeral and changes during important lifetime events for the service - (e.g. service restarts). - If the service has no inherent unique ID that can be used as the value of this attribute - it is recommended to generate a random Version 1 or Version 4 RFC 4122 UUID - (services aiming for reproducible UUIDs may also use Version 5, see RFC 4122 - for more recommendations). - examples: ["my-k8s-pod-deployment-1", "627cc493-f310-47de-96bd-71410b7dec09"] + - ref: service.namespace + - ref: service.instance.id diff --git a/model/resource/telemetry.yaml b/model/resource/telemetry.yaml index 6966b4a853..cbc82ce566 100644 --- a/model/resource/telemetry.yaml +++ b/model/resource/telemetry.yaml @@ -1,57 +1,12 @@ groups: - id: telemetry - prefix: telemetry type: resource brief: > The telemetry SDK used to capture data recorded by the instrumentation libraries. attributes: - - id: sdk.name - type: string + - ref: telemetry.sdk.name requirement_level: required - brief: > - The name of the telemetry SDK as defined above. - note: | - The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. - If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the - `telemetry.sdk.name` attribute to the fully-qualified class or module name of this SDK's main entry point - or another suitable identifier depending on the language. - The identifier `opentelemetry` is reserved and MUST NOT be used in this case. - All custom identifiers SHOULD be stable across different versions of an implementation. - examples: ["opentelemetry"] - - id: sdk.language - type: - allow_custom_values: true - members: - - id: cpp - value: "cpp" - - id: dotnet - value: "dotnet" - - id: erlang - value: "erlang" - - id: go - value: "go" - - id: java - value: "java" - - id: nodejs - value: "nodejs" - - id: php - value: "php" - - id: python - value: "python" - - id: ruby - value: "ruby" - - id: rust - value: "rust" - - id: swift - value: "swift" - - id: webjs - value: "webjs" + - ref: telemetry.sdk.language requirement_level: required - brief: > - The language of the telemetry SDK. - - id: sdk.version - type: string + - ref: telemetry.sdk.version requirement_level: required - brief: > - The version string of the telemetry SDK. - examples: ["1.2.3"] diff --git a/model/resource/telemetry_experimental.yaml b/model/resource/telemetry_experimental.yaml index 6313705517..eb2c508b3a 100644 --- a/model/resource/telemetry_experimental.yaml +++ b/model/resource/telemetry_experimental.yaml @@ -1,12 +1,10 @@ groups: - id: telemetry_experimental - prefix: telemetry type: resource brief: > The telemetry SDK used to capture data recorded by the instrumentation libraries. attributes: - - id: auto.version - type: string - brief: > - The version string of the auto instrumentation agent, if used. - examples: ["1.2.3"] + - ref: telemetry.distro.name + requirement_level: recommended + - ref: telemetry.distro.version + requirement_level: recommended diff --git a/model/resource/webengine.yaml b/model/resource/webengine.yaml index 5e0cdf8fab..9e8a586b0f 100644 --- a/model/resource/webengine.yaml +++ b/model/resource/webengine.yaml @@ -1,23 +1,12 @@ groups: - id: webengine_resource - prefix: webengine type: resource brief: > Resource describing the packaged software running the application code. Web engines are typically executed using process.runtime. attributes: - - id: name - type: string + - ref: webengine.name requirement_level: required - brief: > - The name of the web engine. - examples: ['WildFly'] - - id: version - type: string - brief: > - The version of the web engine. - examples: ['21.0.0'] - - id: description - type: string - brief: > - Additional description of the web engine (e.g. detailed version and edition information). - examples: ['WildFly Full 21.0.0.Final (WildFly Core 13.0.1.Final) - 2.2.2.Final'] + - ref: webengine.version + requirement_level: recommended + - ref: webengine.description + requirement_level: recommended diff --git a/model/scope/exporter/exporter.yaml b/model/scope/exporter/exporter.yaml index 3bbf3fe073..52f47f0b0e 100644 --- a/model/scope/exporter/exporter.yaml +++ b/model/scope/exporter/exporter.yaml @@ -1,30 +1,9 @@ groups: - id: otel.scope - prefix: otel.scope type: resource brief: Attributes used by non-OTLP exporters to represent OpenTelemetry Scope's concepts. attributes: - - id: name - type: string - brief: The name of the instrumentation scope - (`InstrumentationScope.Name` in OTLP). - examples: ['io.opentelemetry.contrib.mongodb'] - - id: version - type: string - brief: The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). - examples: ['1.0.0'] - - id: otel.library - prefix: otel.library - type: resource - brief: > - Span attributes used by non-OTLP exporters to represent OpenTelemetry Scope's concepts. - attributes: - - id: name - type: string - stability: "deprecated" - brief: Deprecated, use the `otel.scope.name` attribute. - examples: ['io.opentelemetry.contrib.mongodb'] - - id: version - type: string - stability: "deprecated" - brief: Deprecated, use the `otel.scope.version` attribute. - examples: ['1.0.0'] + - ref: otel.scope.name + requirement_level: recommended + - ref: otel.scope.version + requirement_level: recommended diff --git a/model/server.yaml b/model/server.yaml deleted file mode 100644 index 3aa189e249..0000000000 --- a/model/server.yaml +++ /dev/null @@ -1,41 +0,0 @@ -groups: - - id: server - prefix: server - type: attribute_group - brief: > - These attributes may be used to describe the server in a connection-based network interaction - where there is one side that initiates the connection (the client is the side that initiates the connection). - This covers all TCP network interactions since TCP is connection-based and one side initiates the - connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the - protocol / API does not expose a clear notion of client and server). - This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS. - attributes: - - id: address - type: string - brief: 'Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known.' - examples: ['example.com'] - - id: port - type: int - brief: 'Logical server port number' - examples: [80, 8080, 443] - - id: socket.domain - type: string - brief: The domain name of an immediate peer. - examples: ['proxy.example.com'] - note: Typically observed from the client side, and represents a proxy or other intermediary domain name. - requirement_level: - recommended: If different than `server.address`. - - id: socket.address - type: string - brief: > - Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from - client, this may represent some proxy server instead of the logical server). - examples: ['10.5.3.2'] - requirement_level: - recommended: If different than `server.address`. - - id: socket.port - type: int - brief: Physical server port. - examples: [16456] - requirement_level: - recommended: If different than `server.port`. diff --git a/model/session.yaml b/model/session.yaml new file mode 100644 index 0000000000..a0efc150e2 --- /dev/null +++ b/model/session.yaml @@ -0,0 +1,20 @@ +groups: + - id: session-id + prefix: session + type: attribute_group + brief: > + Session is defined as the period of time encompassing all activities performed by the application and the actions + executed by the end user. + + Consequently, a Session is represented as a collection of Logs, Events, and Spans emitted by the Client Application + throughout the Session's duration. Each Session is assigned a unique identifier, which is included as an attribute in + the Logs, Events, and Spans generated during the Session's lifecycle. + + When a session reaches end of life, typically due to user inactivity or session timeout, a new session identifier + will be assigned. The previous session identifier may be provided by the instrumentation so that telemetry + backends can link the two sessions. + attributes: + - ref: session.id + requirement_level: opt_in + - ref: session.previous_id + requirement_level: opt_in diff --git a/model/source.yaml b/model/source.yaml deleted file mode 100644 index 63fc1bd4b6..0000000000 --- a/model/source.yaml +++ /dev/null @@ -1,24 +0,0 @@ -groups: - - id: source - prefix: source - type: attribute_group - brief: These attributes may be used to describe the sender of a network exchange/packet. These should be used - when there is no client/server relationship between the two sides, or when that relationship is unknown. - This covers low-level network interactions (e.g. packet tracing) where you don't know if - there was a connection or which side initiated it. - This also covers unidirectional UDP flows and peer-to-peer communication where the - "user-facing" surface of the protocol / API does not expose a clear notion of client and server. - attributes: - - id: domain - type: string - brief: The domain name of the source system. - examples: ['foo.example.com'] - note: This value may be a host name, a fully qualified domain name, or another host naming format. - - id: address - type: string - brief: 'Source address, for example IP address or Unix socket name.' - examples: ['10.5.3.2'] - - id: port - type: int - brief: 'Source port number' - examples: [3389, 2888] diff --git a/model/trace/aws/lambda.yaml b/model/trace/aws/lambda.yaml index 73e77ea747..41943ab8cb 100644 --- a/model/trace/aws/lambda.yaml +++ b/model/trace/aws/lambda.yaml @@ -1,14 +1,8 @@ groups: - id: aws.lambda - prefix: aws.lambda type: span brief: > Span attributes used by AWS Lambda (in addition to general `faas` attributes). attributes: - - id: invoked_arn - type: string - brief: > - The full invoked ARN as provided on the `Context` passed to the function - (`Lambda-Runtime-Invoked-Function-Arn` header on the `/runtime/invocation/next` applicable). - note: This may be different from `cloud.resource_id` if an alias is involved. - examples: ['arn:aws:lambda:us-east-1:123456:function:myfunction:myalias'] + - ref: aws.lambda.invoked_arn + requirement_level: recommended diff --git a/model/trace/cloudevents.yaml b/model/trace/cloudevents.yaml index 6fcf7ae268..604d101c17 100644 --- a/model/trace/cloudevents.yaml +++ b/model/trace/cloudevents.yaml @@ -1,36 +1,18 @@ groups: - id: cloudevents - prefix: cloudevents type: span brief: > This document defines attributes for CloudEvents. CloudEvents is a specification on how to define event data in a standard way. These attributes can be attached to spans when performing operations with CloudEvents, regardless of the protocol being used. attributes: - - id: event_id - type: string + - ref: cloudevents.event_id requirement_level: required - brief: > - The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event. - examples: ['123e4567-e89b-12d3-a456-426614174000', '0001'] - - id: event_source - type: string + - ref: cloudevents.event_source requirement_level: required - brief: > - The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened. - examples: ['https://github.com/cloudevents', '/cloudevents/spec/pull/123', 'my-service' ] - - id: event_spec_version - type: string - brief: > - The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses. - examples: '1.0' - - id: event_type - type: string - brief: > - The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. - examples: ['com.github.pull_request.opened', 'com.example.object.deleted.v2'] - - id: event_subject - type: string - brief: > - The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). - examples: 'mynewfile.jpg' + - ref: cloudevents.event_spec_version + requirement_level: recommended + - ref: cloudevents.event_type + requirement_level: recommended + - ref: cloudevents.event_subject + requirement_level: recommended diff --git a/model/trace/compatibility.yaml b/model/trace/compatibility.yaml index 62f85e5c08..3f906d18cf 100644 --- a/model/trace/compatibility.yaml +++ b/model/trace/compatibility.yaml @@ -1,21 +1,9 @@ groups: - id: opentracing - prefix: opentracing type: span brief: 'This document defines semantic conventions for the OpenTracing Shim' note: > These conventions are used by the OpenTracing Shim layer. attributes: - - id: ref_type - brief: 'Parent-child Reference type' - note: > - The causal relationship between a child Span and a parent Span. - type: - allow_custom_values: false - members: - - id: child_of - value: 'child_of' - brief: 'The parent Span depends on the child Span in some capacity' - - id: follows_from - value: 'follows_from' - brief: 'The parent Span does not depend in any way on the result of the child Span' + - ref: opentracing.ref_type + requirement_level: recommended diff --git a/model/trace/database.yaml b/model/trace/database.yaml index 73f6005d08..9cb433fedd 100644 --- a/model/trace/database.yaml +++ b/model/trace/database.yaml @@ -1,527 +1,274 @@ groups: - - id: db - prefix: db - type: span - brief: > - This document defines the attributes used to perform database client calls. - span_kind: client + - id: trace.db.common + extends: attributes.db.client + type: attribute_group + brief: This group defines the attributes used to perform database client calls. attributes: - - id: system - tag: connection-level - brief: An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. - requirement_level: required - type: - allow_custom_values: true - members: - - id: other_sql - value: 'other_sql' - brief: 'Some other SQL database. Fallback only. See notes.' - - id: mssql - value: 'mssql' - brief: 'Microsoft SQL Server' - - id: mssqlcompact - value: 'mssqlcompact' - brief: 'Microsoft SQL Server Compact' - - id: mysql - value: 'mysql' - brief: 'MySQL' - - id: oracle - value: 'oracle' - brief: 'Oracle Database' - - id: db2 - value: 'db2' - brief: 'IBM Db2' - - id: postgresql - value: 'postgresql' - brief: 'PostgreSQL' - - id: redshift - value: 'redshift' - brief: 'Amazon Redshift' - - id: hive - value: 'hive' - brief: 'Apache Hive' - - id: cloudscape - value: 'cloudscape' - brief: 'Cloudscape' - - id: hsqldb - value: 'hsqldb' - brief: 'HyperSQL DataBase' - - id: progress - value: 'progress' - brief: 'Progress Database' - - id: maxdb - value: 'maxdb' - brief: 'SAP MaxDB' - - id: hanadb - value: 'hanadb' - brief: 'SAP HANA' - - id: ingres - value: 'ingres' - brief: 'Ingres' - - id: firstsql - value: 'firstsql' - brief: 'FirstSQL' - - id: edb - value: 'edb' - brief: 'EnterpriseDB' - - id: cache - value: 'cache' - brief: 'InterSystems Caché' - - id: adabas - value: 'adabas' - brief: 'Adabas (Adaptable Database System)' - - id: firebird - value: 'firebird' - brief: 'Firebird' - - id: derby - value: 'derby' - brief: 'Apache Derby' - - id: filemaker - value: 'filemaker' - brief: 'FileMaker' - - id: informix - value: 'informix' - brief: 'Informix' - - id: instantdb - value: 'instantdb' - brief: 'InstantDB' - - id: interbase - value: 'interbase' - brief: 'InterBase' - - id: mariadb - value: 'mariadb' - brief: 'MariaDB' - - id: netezza - value: 'netezza' - brief: 'Netezza' - - id: pervasive - value: 'pervasive' - brief: 'Pervasive PSQL' - - id: pointbase - value: 'pointbase' - brief: 'PointBase' - - id: sqlite - value: 'sqlite' - brief: 'SQLite' - - id: sybase - value: 'sybase' - brief: 'Sybase' - - id: teradata - value: 'teradata' - brief: 'Teradata' - - id: vertica - value: 'vertica' - brief: 'Vertica' - - id: h2 - value: 'h2' - brief: 'H2' - - id: coldfusion - value: 'coldfusion' - brief: 'ColdFusion IMQ' - - id: cassandra - value: 'cassandra' - brief: 'Apache Cassandra' - - id: hbase - value: 'hbase' - brief: 'Apache HBase' - - id: mongodb - value: 'mongodb' - brief: 'MongoDB' - - id: redis - value: 'redis' - brief: 'Redis' - - id: couchbase - value: 'couchbase' - brief: 'Couchbase' - - id: couchdb - value: 'couchdb' - brief: 'CouchDB' - - id: cosmosdb - value: 'cosmosdb' - brief: 'Microsoft Azure Cosmos DB' - - id: dynamodb - value: 'dynamodb' - brief: 'Amazon DynamoDB' - - id: neo4j - value: 'neo4j' - brief: 'Neo4j' - - id: geode - value: 'geode' - brief: 'Apache Geode' - - id: elasticsearch - value: 'elasticsearch' - brief: 'Elasticsearch' - - id: memcached - value: 'memcached' - brief: 'Memcached' - - id: cockroachdb - value: 'cockroachdb' - brief: 'CockroachDB' - - id: opensearch - value: 'opensearch' - brief: 'OpenSearch' - - id: clickhouse - value: 'clickhouse' - brief: 'ClickHouse' - - id: spanner - value: 'spanner' - brief: 'Cloud Spanner' - - id: trino - value: 'trino' - brief: 'Trino' - - id: connection_string - tag: connection-level - type: string - brief: > - The connection string used to connect to the database. - It is recommended to remove embedded credentials. - examples: 'Server=(localdb)\v11.0;Integrated Security=true;' - - id: user - tag: connection-level - type: string - brief: > - Username for accessing the database. - examples: ['readonly_user', 'reporting_user'] - - id: jdbc.driver_classname - tag: connection-level-tech-specific - type: string - brief: > - The fully-qualified class name of the [Java Database Connectivity (JDBC)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) driver used to connect. - examples: ['org.postgresql.Driver', 'com.microsoft.sqlserver.jdbc.SQLServerDriver'] - - id: name - tag: call-level - type: string - requirement_level: - conditionally_required: If applicable. - brief: > - This attribute is used to report the name of the database being accessed. - For commands that switch the database, this should be set to the target database - (even if the command fails). - note: > - In some SQL databases, the database name to be used is called "schema name". - In case there are multiple layers that could be considered for database name - (e.g. Oracle instance name and schema name), - the database name to be used is the more specific layer (e.g. Oracle schema name). - examples: [ 'customers', 'main' ] - - id: statement - tag: call-level - type: string + - ref: db.query.text requirement_level: recommended: > - Should be collected by default only if there is sanitization that excludes sensitive information. - brief: > - The database statement being executed. - examples: ['SELECT * FROM wuser_table', 'SET mykey "WuValue"'] - - id: operation - tag: call-level - type: string + SHOULD be collected by default only if there is sanitization that excludes sensitive information. + - ref: db.query.parameter + requirement_level: opt_in + + - id: db.tech_specific.network.attributes + type: attribute_group + brief: This group documents attributes that describe database call along with network information. + extends: trace.db.common + attributes: + - ref: network.peer.address requirement_level: - conditionally_required: If `db.statement` is not applicable. - brief: > - The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) - such as `findAndModify`, or the SQL keyword. + recommended note: > - When setting this to an SQL keyword, it is not recommended to - attempt any client-side parsing of `db.statement` just to get this - property, but it should be set if the operation name is provided by - the library being instrumented. - If the SQL statement has an ambiguous operation, or performs more - than one operation, this value may be omitted. - examples: ['findAndModify', 'HMSET', 'SELECT'] - - ref: server.address - tag: connection-level - requirement_level: - conditionally_required: See alternative attributes below. - brief: > - Name of the database host. - - ref: server.port - tag: connection-level - requirement_level: - conditionally_required: If using a port other than the default port for this DBMS and if `server.address` is set. - - ref: server.socket.address - tag: connection-level - - ref: server.socket.port - tag: connection-level - - ref: network.transport - tag: connection-level - - ref: network.type - tag: connection-level - - ref: server.socket.domain - requirement_level: - recommended: If different than `server.address` and if `server.socket.address` is set. - constraints: - - any_of: - - 'server.address' - - 'server.socket.address' + If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. + tag: tech-specific + - ref: network.peer.port + tag: tech-specific + + - id: db + type: span + brief: This span defines the attributes used to perform database client calls. + span_kind: client + extends: trace.db.common - id: db.mssql - prefix: db.mssql type: span - extends: db + extends: db.sql brief: > - Connection-level attributes for Microsoft SQL Server + Attributes for Microsoft SQL Server attributes: - - id: instance_name - tag: connection-level-tech-specific - type: string - note: > - If setting a `db.mssql.instance_name`, `server.port` is no longer - required (but still recommended if non-standard). - brief: > - The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) - connecting to. This name is used to determine the port of a named instance. - examples: 'MSSQLSERVER' + - ref: db.namespace + brief: The name of the database, fully qualified within the server address and port. + note: + When connecting to a default instance, `db.namespace` SHOULD be set to the name of + the database. When connecting to a [named instance](https://learn.microsoft.com/sql/connect/jdbc/building-the-connection-url#named-and-multiple-sql-server-instances), + `db.namespace` SHOULD be set to the combination of instance and database name following the `{instance_name}.{database_name}` pattern. + + For commands that switch the database, this SHOULD be set to the target database (even if the command fails). + examples: ["instance1.products", "customers"] + tag: tech-specific - id: db.cassandra - prefix: db.cassandra type: span - extends: db + extends: db.tech_specific.network.attributes brief: > - Call-level attributes for Cassandra + Attributes for Cassandra attributes: - - ref: db.name - tag: call-level-tech-specific-cassandra - brief: > - The keyspace name in Cassandra. + - ref: db.namespace + brief: The Cassandra keyspace name. + note: For commands that switch the keyspace, this SHOULD be set to the target keyspace (even if the command fails). examples: ["mykeyspace"] - note: For Cassandra the `db.name` should be set to the Cassandra keyspace name. - - id: page_size - type: int - tag: call-level-tech-specific-cassandra - brief: > - The fetch size used for paging, i.e. how many rows will be returned at once. - examples: [5000] - - id: consistency_level - tag: call-level-tech-specific-cassandra - brief: > - The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). - type: - members: - - id: all - value: 'all' - - id: each_quorum - value: 'each_quorum' - - id: quorum - value: 'quorum' - - id: local_quorum - value: 'local_quorum' - - id: one - value: 'one' - - id: two - value: 'two' - - id: three - value: 'three' - - id: local_one - value: 'local_one' - - id: any - value: 'any' - - id: serial - value: 'serial' - - id: local_serial - value: 'local_serial' - - id: table - type: string - tag: call-level-tech-specific-cassandra - requirement_level: recommended - brief: The name of the primary table that the operation is acting upon, including the keyspace name (if applicable). - note: > - This mirrors the db.sql.table attribute but references cassandra rather than sql. - It is not recommended to attempt any client-side parsing of - `db.statement` just to get this property, but it should be set if - it is provided by the library being instrumented. - If the operation is acting upon an anonymous table, or more than one table, this - value MUST NOT be set. - examples: 'mytable' - - id: idempotence - type: boolean - tag: call-level-tech-specific-cassandra - brief: > - Whether or not the query is idempotent. - - id: speculative_execution_count - type: int - tag: call-level-tech-specific-cassandra - brief: > - The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. - examples: [0, 2] - - id: coordinator.id - type: string - tag: call-level-tech-specific-cassandra - brief: > - The ID of the coordinating node for a query. - examples: 'be13faa2-8574-4d71-926d-27f16cf8a7af' - - id: coordinator.dc - type: string - tag: call-level-tech-specific-cassandra - brief: > - The data center of the coordinating node for a query. - examples: 'us-west-2' + tag: tech-specific + - ref: db.cassandra.page_size + tag: tech-specific + - ref: db.cassandra.consistency_level + tag: tech-specific + - ref: db.collection.name + brief: The name of the Cassandra table that the operation is acting upon. + tag: tech-specific + - ref: db.cassandra.idempotence + tag: tech-specific + - ref: db.cassandra.speculative_execution_count + tag: tech-specific + - ref: db.cassandra.coordinator.id + tag: tech-specific + - ref: db.cassandra.coordinator.dc + tag: tech-specific - id: db.hbase - prefix: db.hbase type: span - extends: db + extends: trace.db.common brief: > - Call-level attributes for HBase + Attributes for HBase attributes: - - ref: db.name - tag: call-level-tech-specific - brief: > - The HBase namespace. + - ref: db.namespace + brief: The HBase namespace. + requirement_level: + conditionally_required: If applicable. + note: > + When performing table-related operations, the instrumentations SHOULD extract the namespace from the table name according to + the [HBase table naming conventions](https://hbase.apache.org/book.html#namespace_creation). If namespace is not provided, + instrumentation SHOULD set `db.namespace` value to `default`. examples: ['mynamespace'] - note: For HBase the `db.name` should be set to the HBase namespace. + tag: tech-specific + - ref: db.collection.name + brief: The HBase table name. + requirement_level: + conditionally_required: If applicable. + note: > + If table name includes the namespace, the `db.collection.name` SHOULD be set to the full table name. + examples: ['mytable', 'ns:table'] + tag: tech-specific - id: db.couchdb - prefix: db.couchdb type: span - extends: db + extends: trace.db.common brief: > - Call-level attributes for CouchDB + Attributes for CouchDB attributes: - - ref: db.operation - tag: call-level-tech-specific + - ref: db.operation.name + tag: tech-specific brief: > The HTTP method + the target REST route. examples: ['GET /{db}/{docid}'] note: > - In **CouchDB**, `db.operation` should be set to the HTTP method + + In **CouchDB**, `db.operation.name` should be set to the HTTP method + the target REST route according to the API reference documentation. - For example, when retrieving a document, `db.operation` would be set to + For example, when retrieving a document, `db.operation.name` would be set to (literally, i.e., without replacing the placeholders with concrete values): - [`GET /{db}/{docid}`](http://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid). + [`GET /{db}/{docid}`](https://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid). - id: db.redis - prefix: db.redis type: span - extends: db + extends: db.tech_specific.network.attributes brief: > - Call-level attributes for Redis + Attributes for Redis attributes: - - id: database_index - type: int - requirement_level: - conditionally_required: If other than the default database (`0`). - tag: call-level-tech-specific + - ref: db.namespace brief: > - The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. - To be used instead of the generic `db.name` attribute. - examples: [0, 1, 15] - - ref: db.statement - tag: call-level-tech-specific + The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select). + requirement_level: + conditionally_required: If and only if it can be captured reliably. + note: > + 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. + + For commands that switch the database, this SHOULD be set to the target database (even if the command fails). + examples: ["0", "1", "15"] + tag: tech-specific + - ref: db.query.text + tag: tech-specific brief: > The full syntax of the Redis CLI command. examples: ["HMSET myhash field1 'Hello' field2 'World'"] note: > - For **Redis**, the value provided for `db.statement` SHOULD correspond to the syntax of the Redis CLI. - If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.statement`. + For **Redis**, the value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. + If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`. + - id: db.mongodb - prefix: db.mongodb type: span - extends: db + extends: trace.db.common brief: > - Call-level attributes for MongoDB + Attributes for MongoDB attributes: - - id: collection - type: string - requirement_level: required - tag: call-level-tech-specific + - ref: db.operation.name brief: > - The collection being accessed within the database stated in `db.name`. - examples: [ 'customers', 'products' ] + The name of the command being executed. + note: > + See [MongoDB database commands](https://www.mongodb.com/docs/manual/reference/command/). + examples: ['findAndModify', 'getMore', 'update'] + tag: tech-specific + - ref: db.collection.name + brief: + The MongoDB collection being accessed within the database stated in `db.namespace`. + requirement_level: required + tag: tech-specific + - ref: db.namespace + brief: The MongoDB database name. + note: | + + tag: tech-specific - id: db.elasticsearch - prefix: db.elasticsearch type: span - extends: db + extends: db.tech_specific.network.attributes brief: > - Call-level attributes for Elasticsearch + Attributes for Elasticsearch attributes: - ref: http.request.method requirement_level: required - - ref: db.operation + tag: tech-specific + - ref: db.operation.name requirement_level: required - brief: The endpoint identifier for the request. + note: This SHOULD be the endpoint identifier for the request. examples: [ 'search', 'ml.close_job', 'cat.aliases' ] + tag: tech-specific - ref: url.full requirement_level: required examples: [ 'https://localhost:9200/index/_search?q=user.id:kimchy' ] - - ref: db.statement + tag: tech-specific + - ref: db.query.text requirement_level: recommended: > Should be collected by default for search-type queries and only if there is sanitization that excludes 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\"}}}"' ] + tag: tech-specific - ref: server.address + tag: tech-specific - ref: server.port + tag: tech-specific + - 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. + tag: tech-specific + - 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. + tag: tech-specific + - ref: db.elasticsearch.path_parts + requirement_level: + conditionally_required: when the url has dynamic values + tag: tech-specific - id: db.sql - prefix: 'db.sql' type: span - extends: 'db' + extends: trace.db.common brief: > - Call-level attributes for SQL databases + Attributes for SQL databases attributes: - - id: table - tag: call-level-tech-specific - type: string - requirement_level: recommended - brief: The name of the primary table that the operation is acting upon, including the database name (if applicable). + - ref: db.operation.name note: > - It is not recommended to attempt any client-side parsing of - `db.statement` just to get this property, but it should be set if - it is provided by the library being instrumented. - If the operation is acting upon an anonymous table, or more than one table, this - value MUST NOT be set. - examples: ['public.users', 'customers'] + This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`. + In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed. + examples: ['SELECT', 'INSERT', 'UPDATE', 'DELETE', 'CREATE', 'mystoredproc'] + tag: tech-specific + - ref: db.collection.name + brief: The name of the SQL table that the operation is acting upon. + examples: ['users', 'dbo.products'] + tag: tech-specific + - ref: db.namespace + note: | + If a database system has multiple namespace components, they SHOULD be concatenated + (potentially using database system specific conventions) from most general to most + specific namespace component, and more specific namespaces SHOULD NOT be captured without + the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid. + + Unless specified by the system-specific semantic convention, the `db.namespace` attribute matches + the name of the database being accessed. + + The database name can usually be obtained with database driver API such as + [JDBC `Connection.getCatalog()`](https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html#getCatalog--) + or [.NET `SqlConnection.Database`](https://learn.microsoft.com/dotnet/api/system.data.sqlclient.sqlconnection.database). + + Some database drivers don't detect when the current database is changed (for example, with SQL `USE database` statement). + Instrumentations that parse SQL statements MAY use the database name provided + in the connection string and keep track of the currently selected database name. + + For commands that switch the database, this SHOULD be set to the target database (even if the command fails). + + If instrumentation cannot reliably determine the current database name, it SHOULD NOT set `db.namespace`. + tag: tech-specific - id: db.cosmosdb type: span - extends: db + extends: trace.db.common prefix: db.cosmosdb brief: > - Call-level attributes for Cosmos DB. + Attributes for Cosmos DB. attributes: - - id: client_id - type: string - brief: Unique Cosmos client instance id. - examples: '3ba4827d-4422-483f-b59f-85b74211c11d' - - id: operation_type - type: - allow_custom_values: true - members: - - id: invalid - value: 'Invalid' - - id: create - value: 'Create' - - id: patch - value: 'Patch' - - id: read - value: 'Read' - - id: read_feed - value: 'ReadFeed' - - id: delete - value: 'Delete' - - id: replace - value: 'Replace' - - id: execute - value: 'Execute' - - id: query - value: 'Query' - - id: head - value: 'Head' - - id: head_feed - value: 'HeadFeed' - - id: upsert - value: 'Upsert' - - id: batch - value: 'Batch' - - id: query_plan - value: 'QueryPlan' - - id: execute_javascript - value: 'ExecuteJavaScript' - brief: CosmosDB Operation Type. + - ref: db.cosmosdb.client_id + tag: tech-specific + - ref: db.cosmosdb.operation_type requirement_level: conditionally_required: when performing one of the operations in this list + tag: tech-specific - ref: user_agent.original brief: 'Full user-agent string is generated by Cosmos DB SDK' note: > @@ -536,53 +283,28 @@ groups: Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it). Default value is "NS". examples: ['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\|'] - - id: connection_mode - type: - allow_custom_values: false - members: - - id: gateway - value: 'gateway' - brief: Gateway (HTTP) connections mode - - id: direct - value: 'direct' - brief: Direct connection. - brief: Cosmos client connection mode. + tag: tech-specific + - ref: db.cosmosdb.connection_mode requirement_level: conditionally_required: if not `direct` (or pick gw as default) - - id: container - type: string - brief: Cosmos DB container name. + tag: tech-specific + - ref: db.collection.name + brief: > + Cosmos DB container name. requirement_level: conditionally_required: if available - examples: 'anystring' - - id: request_content_length - type: int - brief: Request payload size in bytes - - id: status_code - type: int - brief: Cosmos DB status code. - examples: [200, 201] + tag: tech-specific + - ref: db.cosmosdb.request_content_length + tag: tech-specific + - ref: db.cosmosdb.status_code requirement_level: conditionally_required: if response was received - - id: sub_status_code - type: int - brief: Cosmos DB sub status code. - examples: [1000, 1002] + tag: tech-specific + - ref: db.cosmosdb.sub_status_code requirement_level: conditionally_required: when response was received and contained sub-code. - - id: request_charge - type: double - brief: RU consumed for that operation - examples: [46.18, 1.0] + tag: tech-specific + - ref: db.cosmosdb.request_charge requirement_level: conditionally_required: when available - - - id: db.tech - type: span - brief: "Semantic convention group for specific technologies" - constraints: - - include: 'db.cassandra' - - include: 'db.redis' - - include: 'db.mongodb' - - include: 'db.sql' - - include: 'db.cosmosdb' + tag: tech-specific diff --git a/model/trace/exporter/exporter.yaml b/model/trace/exporter/exporter.yaml index bba71aac9b..0c4e8c6a8f 100644 --- a/model/trace/exporter/exporter.yaml +++ b/model/trace/exporter/exporter.yaml @@ -1,21 +1,9 @@ groups: - id: otel_span - prefix: otel type: span brief: Span attributes used by non-OTLP exporters to represent OpenTelemetry Span's concepts. attributes: - - id: status_code - type: - allow_custom_values: false - members: - - id: ok - value: OK - brief: 'The operation has been validated by an Application developer or Operator to have completed successfully.' - - id: error - value: ERROR - brief: 'The operation contains an error.' - brief: Name of the code, either "OK" or "ERROR". MUST NOT be set if the status code is UNSET. - - id: status_description - type: string - brief: Description of the Status if it has a value, otherwise not set. - examples: ['resource not found'] + - ref: otel.status_code + requirement_level: recommended + - ref: otel.status_description + requirement_level: recommended diff --git a/model/trace/faas.yaml b/model/trace/faas.yaml index d30d41920a..5b3e53b09b 100644 --- a/model/trace/faas.yaml +++ b/model/trace/faas.yaml @@ -7,8 +7,7 @@ groups: runs without provisioning or managing of servers (also known as serverless functions or Function as a Service (FaaS)) with spans. attributes: - - id: trigger - brief: 'Type of the trigger which caused this function invocation.' + - ref: faas.trigger note: | For the server/consumer span on the incoming side, `faas.trigger` MUST be set. @@ -19,174 +18,77 @@ groups: trigger that corresponding incoming would have (i.e., this has nothing to do with the underlying transport used to make the API call to invoke the lambda, which is often HTTP). - type: - allow_custom_values: false - members: - - id: datasource - value: 'datasource' - brief: 'A response to some data source operation such as a database or filesystem read/write.' - - id: http - value: 'http' - brief: 'To provide an answer to an inbound HTTP request' - - id: pubsub - value: 'pubsub' - brief: 'A function is set to be executed when messages are sent to a messaging system.' - - id: timer - value: 'timer' - brief: 'A function is scheduled to be executed regularly.' - - id: other - value: 'other' - brief: 'If none of the others apply' - - id: invocation_id - type: string - brief: 'The invocation ID of the current function invocation.' - examples: 'af9d5aa4-a685-4c5f-a22b-444f80b3cc28' + - ref: faas.invocation_id - ref: cloud.resource_id + - id: faas_span.datasource prefix: faas.document type: span - extends: faas_span brief: > Semantic Convention for FaaS triggered as a response to some data source operation such as a database or filesystem read/write. attributes: - - id: collection - type: string + - ref: faas.document.collection requirement_level: required - brief: > - The name of the source on which the triggering operation was performed. - For example, in Cloud Storage or S3 corresponds to the bucket name, - and in Cosmos DB to the database name. - examples: ['myBucketName', 'myDbName'] - - id: operation + - ref: faas.document.operation requirement_level: required - type: - allow_custom_values: true - members: - - id: insert - value: 'insert' - brief: 'When a new object is created.' - - id: edit - value: 'edit' - brief: 'When an object is modified.' - - id: delete - value: 'delete' - brief: 'When an object is deleted.' - brief: 'Describes the type of the operation that was performed on the data.' - - id: time - type: string - brief: > - A string containing the time when the data was accessed in the - [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) - format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). - examples: "2020-01-23T13:47:06Z" - - id: name - type: string - brief: > - The document name/table subjected to the operation. - For example, in Cloud Storage or S3 is the name of - the file, and in Cosmos DB the table name. - examples: ["myFile.txt", "myTableName"] + - ref: faas.document.time + - ref: faas.document.name - id: faas_span.http type: span - extends: faas_span brief: > Semantic Convention for FaaS triggered as a response to some data source operation such as a database or filesystem read/write. - constraints: - - include: trace.http.server - id: faas_span.pubsub type: span - extends: faas_span brief: > Semantic Convention for FaaS set to be executed when messages are sent to a messaging system. - constraints: - - include: messaging - id: faas_span.timer - extends: faas_span prefix: faas type: span brief: > Semantic Convention for FaaS scheduled to be executed regularly. attributes: - - id: time - type: string - brief: > - A string containing the function invocation time in the - [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) - format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). - examples: "2020-01-23T13:47:06Z" - - id: cron - type: string - brief: > - A string containing the schedule period as - [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). - examples: "0/5 * * * ? *" + - ref: faas.time + - ref: faas.cron - id: faas_span.in - extends: faas_span span_kind: server prefix: faas type: span brief: > Contains additional attributes for incoming FaaS spans. attributes: - - id: coldstart - type: boolean - brief: > - A boolean that is true if the serverless function is executed for the - first time (aka cold-start). + - ref: faas.coldstart - ref: faas.trigger requirement_level: required + note: | + For the server/consumer span on the incoming side, + `faas.trigger` MUST be set. + + Clients invoking FaaS instances usually cannot set `faas.trigger`, + since they would typically need to look in the payload to determine + the event type. If clients set it, it should be the same as the + trigger that corresponding incoming would have (i.e., this has + nothing to do with the underlying transport used to make the API + call to invoke the lambda, which is often HTTP). - id: faas_span.out - extends: faas_span span_kind: client prefix: faas type: span brief: > Contains additional attributes for outgoing FaaS spans. attributes: - - id: invoked_name - type: string + - ref: faas.invoked_name requirement_level: required - brief: > - The name of the invoked function. - note: > - SHOULD be equal to the `faas.name` resource attribute of the - invoked function. - examples: 'my-function' - - id: invoked_provider - type: - allow_custom_values: true - members: - - id: 'alibaba_cloud' - value: 'alibaba_cloud' - brief: 'Alibaba Cloud' - - id: 'aws' - value: 'aws' - brief: 'Amazon Web Services' - - id: 'azure' - value: 'azure' - brief: 'Microsoft Azure' - - id: 'gcp' - value: 'gcp' - brief: 'Google Cloud Platform' - - id: 'tencent_cloud' - value: 'tencent_cloud' - brief: 'Tencent Cloud' + - ref: faas.invoked_provider requirement_level: required - brief: > - The cloud provider of the invoked function. - note: > - SHOULD be equal to the `cloud.provider` resource attribute of the - invoked function. - - id: invoked_region - type: string + - ref: faas.invoked_region requirement_level: conditionally_required: > For some cloud providers, like AWS or GCP, the region in which a @@ -196,9 +98,3 @@ groups: `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional. - brief: > - The cloud region of the invoked function. - note: > - SHOULD be equal to the `cloud.region` resource attribute of the - invoked function. - examples: 'eu-central-1' diff --git a/model/trace/feature-flag.yaml b/model/trace/feature-flag.yaml index 50706ba2d7..8aae493385 100644 --- a/model/trace/feature-flag.yaml +++ b/model/trace/feature-flag.yaml @@ -1,34 +1,14 @@ groups: - id: feature_flag - prefix: feature_flag type: event + name: feature_flag brief: > This semantic convention defines the attributes used to represent a feature flag evaluation as an event. attributes: - - id: key - type: string + - ref: feature_flag.key requirement_level: required - brief: The unique identifier of the feature flag. - examples: ["logo-color"] - - id: provider_name - type: string + - ref: feature_flag.provider_name requirement_level: recommended - brief: The name of the service provider that performs the flag evaluation. - examples: ["Flag Manager"] - - id: variant - type: string + - ref: feature_flag.variant requirement_level: recommended - examples: ["red", "true", "on"] - brief: > - SHOULD be a semantic identifier for a value. If one is unavailable, a - stringified version of the value can be used. - note: |- - A semantic identifier, commonly referred to as a variant, provides a means - for referring to a value without including the value itself. This can - provide additional context for understanding the meaning behind a value. - For example, the variant `red` maybe be used for the value `#c05543`. - - A stringified version of the value can be used in situations where a - semantic identifier is unavailable. String representation of the value - should be determined by the implementer. diff --git a/model/trace/gen-ai.yaml b/model/trace/gen-ai.yaml new file mode 100644 index 0000000000..bf1d112e37 --- /dev/null +++ b/model/trace/gen-ai.yaml @@ -0,0 +1,68 @@ +groups: + - id: gen_ai.request + 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. + 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 + custom model, the value should have a more specific name than the base model that's been fine-tuned. + - 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.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 + 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 + requirement_level: recommended + - ref: gen_ai.usage.completion_tokens + requirement_level: recommended + events: + - gen_ai.content.prompt + - gen_ai.content.completion + + - id: gen_ai.content.prompt + name: gen_ai.content.prompt + type: event + brief: > + In the lifetime of an LLM span, events for prompts sent and completions received + may be created, depending on the configuration of the instrumentation. + attributes: + - ref: gen_ai.prompt + requirement_level: + conditionally_required: if and only if corresponding event is enabled + note: > + It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + + - id: gen_ai.content.completion + name: gen_ai.content.completion + type: event + brief: > + In the lifetime of an LLM span, events for prompts sent and completions received + may be created, depending on the configuration of the instrumentation. + attributes: + - ref: gen_ai.completion + requirement_level: + conditionally_required: if and only if corresponding event is enabled + note: > + It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) diff --git a/model/trace/general.yaml b/model/trace/general.yaml deleted file mode 100644 index 545bce5cab..0000000000 --- a/model/trace/general.yaml +++ /dev/null @@ -1,249 +0,0 @@ -groups: - - id: network-core - prefix: network - type: attribute_group - brief: > - These attributes may be used for any network related operation. - attributes: - - id: transport - type: - allow_custom_values: true - members: - - id: tcp - value: 'tcp' - brief: "TCP" - - id: udp - value: 'udp' - brief: "UDP" - - id: pipe - value: "pipe" - brief: 'Named or anonymous pipe. See note below.' - - id: unix - value: 'unix' - brief: "Unix domain socket" - brief: > - [OSI Transport Layer](https://osi-model.com/transport-layer/) or - [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). - The value SHOULD be normalized to lowercase. - examples: ['tcp', 'udp'] - - id: type - type: - allow_custom_values: true - members: - - id: ipv4 - value: 'ipv4' - brief: "IPv4" - - id: ipv6 - value: 'ipv6' - brief: "IPv6" - brief: > - [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. - The value SHOULD be normalized to lowercase. - examples: ['ipv4', 'ipv6'] - - id: protocol.name - type: string - brief: > - [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. - The value SHOULD be normalized to lowercase. - examples: ['amqp', 'http', 'mqtt'] - - id: protocol.version - type: string - brief: 'Version of the application layer protocol used. See note below.' - examples: '3.1.1' - note: > - `network.protocol.version` refers to the version of the protocol used and might be - different from the protocol client's version. If the HTTP client used has a version - of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. - - - id: network-connection-and-carrier - prefix: network - type: attribute_group - brief: > - These attributes may be used for any network related operation. - attributes: - - id: connection.type - type: - allow_custom_values: true - members: - - id: wifi - value: "wifi" - - id: wired - value: "wired" - - id: cell - value: "cell" - - id: unavailable - value: "unavailable" - - id: unknown - value: "unknown" - brief: 'The internet connection type.' - examples: 'wifi' - - id: connection.subtype - type: - allow_custom_values: true - members: - - id: gprs - brief: GPRS - value: "gprs" - - id: edge - brief: EDGE - value: "edge" - - id: umts - brief: UMTS - value: "umts" - - id: cdma - brief: CDMA - value: "cdma" - - id: evdo_0 - brief: EVDO Rel. 0 - value: "evdo_0" - - id: evdo_a - brief: "EVDO Rev. A" - value: "evdo_a" - - id: cdma2000_1xrtt - brief: CDMA2000 1XRTT - value: "cdma2000_1xrtt" - - id: hsdpa - brief: HSDPA - value: "hsdpa" - - id: hsupa - brief: HSUPA - value: "hsupa" - - id: hspa - brief: HSPA - value: "hspa" - - id: iden - brief: IDEN - value: "iden" - - id: evdo_b - brief: "EVDO Rev. B" - value: "evdo_b" - - id: lte - brief: LTE - value: "lte" - - id: ehrpd - brief: EHRPD - value: "ehrpd" - - id: hspap - brief: HSPAP - value: "hspap" - - id: gsm - brief: GSM - value: "gsm" - - id: td_scdma - brief: TD-SCDMA - value: "td_scdma" - - id: iwlan - brief: IWLAN - value: "iwlan" - - id: nr - brief: "5G NR (New Radio)" - value: "nr" - - id: nrnsa - brief: "5G NRNSA (New Radio Non-Standalone)" - value: "nrnsa" - - id: lte_ca - brief: LTE CA - value: "lte_ca" - brief: 'This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection.' - examples: 'LTE' - - id: carrier.name - type: string - brief: "The name of the mobile carrier." - examples: "sprint" - - id: carrier.mcc - type: string - brief: "The mobile carrier country code." - examples: "310" - - id: carrier.mnc - type: string - brief: "The mobile carrier network code." - examples: "001" - - id: carrier.icc - type: string - brief: "The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network." - examples: "DE" - - id: peer - prefix: peer - type: span - brief: "Operations that access some remote service." - attributes: - - id: service - type: string - brief: > - The [`service.name`](/docs/resource/README.md#service) - of the remote service. SHOULD be equal to the actual `service.name` - resource attribute of the remote service if any. - examples: "AuthTokenCache" - - id: identity - prefix: enduser - type: span - brief: > - These attributes may be used for any operation with an authenticated and/or authorized enduser. - attributes: - - id: id - type: string - brief: > - Username or client_id extracted from the access token or - [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) - header in the inbound request from outside the system. - examples: 'username' - - id: role - type: string - brief: 'Actual/assumed role the client is making the request under extracted from token or application security context.' - examples: 'admin' - - id: scope - type: string - brief: > - Scopes or granted authorities the client currently possesses extracted from token - or application security context. The value would come from the scope associated - with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3) - or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). - examples: 'read:message, write:files' - - id: thread - prefix: thread - type: span - brief: > - These attributes may be used for any operation to store information about a thread that started a span. - attributes: - - id: id - type: int - brief: > - Current "managed" thread ID (as opposed to OS thread ID). - examples: 42 - - id: name - type: string - brief: > - Current thread name. - examples: main - - id: code - prefix: code - type: span - brief: > - These attributes allow to report this unit of code and therefore to provide more context about the span. - attributes: - - id: function - type: string - brief: > - The method or function name, or equivalent (usually rightmost part of the code unit's name). - examples: serveRequest - - id: namespace - type: string - brief: > - The "namespace" within which `code.function` is defined. Usually the qualified class or module name, - such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. - examples: com.example.MyHttpService - - id: filepath - type: string - brief: > - The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). - examples: /usr/local/MyApplication/content_root/app/index.php - - id: lineno - type: int - brief: > - The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. - examples: 42 - - id: column - type: int - brief: > - The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. - examples: 16 diff --git a/model/trace/http.yaml b/model/trace/http.yaml index 53898fb483..9bfadac3c9 100644 --- a/model/trace/http.yaml +++ b/model/trace/http.yaml @@ -1,145 +1,96 @@ groups: - - id: trace.http.common - prefix: http - extends: attributes.http.common - type: attribute_group - brief: 'This document defines semantic conventions for HTTP client and server Spans.' - note: > - These conventions can be used for http and https schemes - and various HTTP versions like 1.1, 2 and SPDY. - attributes: - - id: request.method_original - type: string - requirement_level: - conditionally_required: If and only if it's different than `http.request.method`. - brief: Original HTTP method sent by the client in the request line. - examples: ["GeT", "ACL", "foo"] - - id: request.body.size - type: int - brief: > - The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and - is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) - header. For requests using transport encoding, this should be the compressed size. - examples: 3495 - - id: response.body.size - type: int - brief: > - The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and - is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) - header. For requests using transport encoding, this should be the compressed size. - examples: 3495 - - ref: http.request.method - sampling_relevant: true - - ref: network.transport - requirement_level: - conditionally_required: If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). - - ref: network.type - - ref: user_agent.original - - id: trace.http.client - prefix: http type: span extends: attributes.http.client span_kind: client brief: 'Semantic Convention for HTTP Client' + stability: stable attributes: - - id: resend_count - type: int - brief: > - The ordinal number of request resending attempt (for any reason, including redirects). - note: > - The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what - was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, - or any other). + - ref: http.request.method + sampling_relevant: true + - ref: http.request.method_original + requirement_level: + conditionally_required: If and only if it's different than `http.request.method`. + - ref: http.request.resend_count requirement_level: recommended: if and only if request was retried. - examples: 3 + - ref: http.request.header + requirement_level: opt_in + - ref: http.response.header + requirement_level: opt_in - ref: server.address sampling_relevant: true - requirement_level: required - brief: > - Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: | - Determined by using the first of the following that applies - - - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form - - Host identifier of the `Host` header - - If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then - `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. - ref: server.port sampling_relevant: true - requirement_level: - conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). - brief: > - Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: > - When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match - URI port identifier, otherwise it MUST match `Host` header port identifier. - - ref: server.socket.domain - - ref: server.socket.address - - ref: server.socket.port - ref: url.full sampling_relevant: true requirement_level: required + - ref: user_agent.original + requirement_level: opt_in + - ref: url.scheme + - ref: network.peer.address + - ref: network.peer.port + requirement_level: + recommended: If `network.peer.address` is set. + - ref: network.transport + requirement_level: opt_in + note: > + Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. + Other obscure implementations are possible. + - id: trace.http.client.experimental + type: attribute_group + brief: 'Experimental attributes for HTTP Client spans' + stability: experimental + attributes: + - ref: http.request.size + requirement_level: opt_in + - ref: http.response.size + requirement_level: opt_in + - ref: http.request.body.size + requirement_level: opt_in + - ref: http.response.body.size + requirement_level: opt_in - id: trace.http.server - prefix: http type: span extends: attributes.http.server span_kind: server brief: 'Semantic Convention for HTTP Server' + stability: stable attributes: + - ref: http.request.method + sampling_relevant: true + - ref: http.request.method_original + requirement_level: + conditionally_required: If and only if it's different than `http.request.method`. + - ref: http.route + - ref: http.request.header + sampling_relevant: true + requirement_level: opt_in + - ref: http.response.header + requirement_level: opt_in - ref: server.address - requirement_level: recommended sampling_relevant: true - brief: > - Name of the local HTTP server that received the request. - note: | - Determined by using the first of the following that applies - - - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only - include host identifier. - - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. - - Host identifier of the `Host` header - - SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. - ref: server.port sampling_relevant: true - requirement_level: - recommended: If not default (`80` for `http` scheme, `443` for `https`). - brief: > - Port of the local HTTP server that received the request. - note: | - Determined by using the first of the following that applies - - - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. - - Port identifier of the `Host` header - - ref: server.socket.address + - ref: network.local.address requirement_level: opt_in brief: Local socket address. Useful in case of a multi-IP host. - - ref: server.socket.port + - ref: network.local.port requirement_level: opt_in brief: Local socket port. Useful in case of a multi-port host. - ref: client.address + sampling_relevant: true note: > The IP address of the original client behind all proxies, if - known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded), - [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For), or a similar header). + known (e.g. from [Forwarded#for](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#for), + [X-Forwarded-For](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-For), or a similar header). Otherwise, the immediate client peer address. examples: ['83.164.160.102'] - ref: client.port - brief: > - The port of the original client behind all proxies, if - known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). - Otherwise, the immediate client peer port. - - ref: client.socket.address - - ref: client.socket.port + requirement_level: opt_in + brief: The port of whichever client was captured in `client.address`. - ref: url.path requirement_level: required sampling_relevant: true @@ -149,5 +100,28 @@ groups: sampling_relevant: true - ref: url.scheme sampling_relevant: true - requirement_level: required - examples: ["http", "https"] + - ref: user_agent.original + sampling_relevant: true + - ref: network.peer.address + - ref: network.peer.port + requirement_level: + recommended: If `network.peer.address` is set. + - ref: network.transport + requirement_level: opt_in + note: > + Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. + Other obscure implementations are possible. + + - id: trace.http.server.experimental + type: attribute_group + brief: 'Experimental attributes for HTTP Server spans' + stability: experimental + attributes: + - ref: http.request.size + requirement_level: opt_in + - ref: http.response.size + requirement_level: opt_in + - ref: http.request.body.size + requirement_level: opt_in + - ref: http.response.body.size + requirement_level: opt_in diff --git a/model/trace/instrumentation/aws-sdk.yml b/model/trace/instrumentation/aws-sdk.yml index 90b6d1c967..aac648e688 100644 --- a/model/trace/instrumentation/aws-sdk.yml +++ b/model/trace/instrumentation/aws-sdk.yml @@ -26,12 +26,8 @@ groups: examples: - GetItem - PutItem - - id: request_id - type: string - brief: "The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`." - examples: - - 79b9da39-b7ae-508a-a6bc-864b2829c622 - - C9ER4AJX75574TDJ + - ref: aws.request_id + requirement_level: recommended - id: dynamodb.all type: span @@ -45,219 +41,104 @@ groups: - id: dynamodb.shared extends: aws - prefix: aws.dynamodb type: span brief: "Attributes that exist for multiple DynamoDB request types." attributes: - - ref: db.operation + - ref: db.operation.name brief: "The same value as `rpc.method`." examples: - GetItem - PutItem - - id: table_names - type: string[] - brief: The keys in the `RequestItems` object field. - examples: - - Users - - Cats - - id: consumed_capacity - type: string[] - brief: "The JSON-serialized value of each item in the `ConsumedCapacity` response field." - examples: - - '{ - "CapacityUnits": number, - "GlobalSecondaryIndexes": { - "string" : { - "CapacityUnits": number, - "ReadCapacityUnits": number, - "WriteCapacityUnits": number - } - }, - "LocalSecondaryIndexes": { - "string" : { - "CapacityUnits": number, - "ReadCapacityUnits": number, - "WriteCapacityUnits": number - } - }, - "ReadCapacityUnits": number, - "Table": { - "CapacityUnits": number, - "ReadCapacityUnits": number, - "WriteCapacityUnits": number - }, - "TableName": "string", - "WriteCapacityUnits": number - }' - - id: item_collection_metrics - type: string - brief: "The JSON-serialized value of the `ItemCollectionMetrics` response field." - examples: - - '{ - "string" : [ - { - "ItemCollectionKey": { - "string" : { - "B": blob, - "BOOL": boolean, - "BS": [ blob ], - "L": [ - "AttributeValue" - ], - "M": { - "string" : "AttributeValue" - }, - "N": "string", - "NS": [ "string" ], - "NULL": boolean, - "S": "string", - "SS": [ "string" ] - } - }, - "SizeEstimateRangeGB": [ number ] - } - ] - }' - - id: provisioned_read_capacity - type: double - brief: "The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter." - examples: - - 1.0 - - 2.0 - - id: provisioned_write_capacity - type: double - brief: "The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter." - examples: - - 1.0 - - 2.0 - - id: consistent_read - type: boolean - brief: "The value of the `ConsistentRead` request parameter." - - id: projection - type: string - brief: "The value of the `ProjectionExpression` request parameter." - examples: - - Title - - Title, Price, Color - - Title, Description, RelatedItems, ProductReviews - - id: limit - type: int - brief: "The value of the `Limit` request parameter." - examples: - - 10 - - id: attributes_to_get - type: string[] - brief: "The value of the `AttributesToGet` request parameter." - examples: - - lives - - id - - id: index_name - type: string - brief: "The value of the `IndexName` request parameter." - examples: - - name_to_group - - id: select - type: string - brief: "The value of the `Select` request parameter." - examples: - - ALL_ATTRIBUTES - - COUNT + - ref: aws.dynamodb.table_names + requirement_level: recommended + - ref: aws.dynamodb.consumed_capacity + requirement_level: recommended + - ref: aws.dynamodb.item_collection_metrics + requirement_level: recommended + - ref: aws.dynamodb.provisioned_read_capacity + requirement_level: recommended + - ref: aws.dynamodb.provisioned_write_capacity + requirement_level: recommended + - ref: aws.dynamodb.consistent_read + requirement_level: recommended + - ref: aws.dynamodb.projection + requirement_level: recommended + - ref: aws.dynamodb.limit + requirement_level: recommended + - ref: aws.dynamodb.attributes_to_get + requirement_level: recommended + - ref: aws.dynamodb.index_name + requirement_level: recommended + - ref: aws.dynamodb.select + requirement_level: recommended - id: dynamodb.batchgetitem brief: DynamoDB.BatchGetItem extends: aws - prefix: aws.dynamodb type: span attributes: - ref: aws.dynamodb.table_names + requirement_level: recommended - ref: aws.dynamodb.consumed_capacity + requirement_level: recommended - id: dynamodb.batchwriteitem brief: DynamoDB.BatchWriteItem extends: aws - prefix: aws.dynamodb type: span attributes: - ref: aws.dynamodb.table_names + requirement_level: recommended - ref: aws.dynamodb.consumed_capacity + requirement_level: recommended - ref: aws.dynamodb.item_collection_metrics + requirement_level: recommended - id: dynamodb.createtable brief: DynamoDB.CreateTable extends: aws - prefix: aws.dynamodb type: span attributes: - - id: global_secondary_indexes - type: string[] - brief: "The JSON-serialized value of each item of the `GlobalSecondaryIndexes` request field" - examples: - - '{ - "IndexName": "string", - "KeySchema": [ - { - "AttributeName": "string", - "KeyType": "string" - } - ], - "Projection": { - "NonKeyAttributes": [ "string" ], - "ProjectionType": "string" - }, - "ProvisionedThroughput": { - "ReadCapacityUnits": number, - "WriteCapacityUnits": number - } - }' - - id: local_secondary_indexes - type: string[] - brief: "The JSON-serialized value of each item of the `LocalSecondaryIndexes` request field." - examples: - - '{ - "IndexArn": "string", - "IndexName": "string", - "IndexSizeBytes": number, - "ItemCount": number, - "KeySchema": [ - { - "AttributeName": "string", - "KeyType": "string" - } - ], - "Projection": { - "NonKeyAttributes": [ "string" ], - "ProjectionType": "string" - } - }' + - ref: aws.dynamodb.global_secondary_indexes + requirement_level: recommended + - ref: aws.dynamodb.local_secondary_indexes + requirement_level: recommended - ref: aws.dynamodb.table_names + requirement_level: recommended brief: "A single-element array with the value of the TableName request parameter." examples: - Users - ref: aws.dynamodb.consumed_capacity + requirement_level: recommended - ref: aws.dynamodb.item_collection_metrics + requirement_level: recommended - ref: aws.dynamodb.provisioned_read_capacity + requirement_level: recommended - ref: aws.dynamodb.provisioned_write_capacity + requirement_level: recommended - id: dynamodb.deleteitem brief: DynamoDB.DeleteItem extends: aws - prefix: aws.dynamodb type: span attributes: - ref: aws.dynamodb.table_names + requirement_level: recommended brief: "A single-element array with the value of the TableName request parameter." examples: - Users - ref: aws.dynamodb.consumed_capacity + requirement_level: recommended - ref: aws.dynamodb.item_collection_metrics + requirement_level: recommended - id: dynamodb.deletetable brief: DynamoDB.DeleteTable extends: aws - prefix: aws.dynamodb type: span attributes: - ref: aws.dynamodb.table_names + requirement_level: recommended brief: "A single-element array with the value of the TableName request parameter." examples: - Users @@ -265,10 +146,10 @@ groups: - id: dynamodb.describetable brief: DynamoDB.DescribeTable extends: aws - prefix: aws.dynamodb type: span attributes: - ref: aws.dynamodb.table_names + requirement_level: recommended brief: "A single-element array with the value of the TableName request parameter." examples: - Users @@ -276,241 +157,154 @@ groups: - id: dynamodb.getitem brief: DynamoDB.GetItem extends: aws - prefix: aws.dynamodb type: span attributes: - ref: aws.dynamodb.table_names + requirement_level: recommended brief: "A single-element array with the value of the TableName request parameter." examples: - Users - ref: aws.dynamodb.consumed_capacity + requirement_level: recommended - ref: aws.dynamodb.consistent_read + requirement_level: recommended - ref: aws.dynamodb.projection + requirement_level: recommended - id: dynamodb.listtables brief: DynamoDB.ListTables extends: aws - prefix: aws.dynamodb type: span attributes: - - id: exclusive_start_table - type: string - brief: "The value of the `ExclusiveStartTableName` request parameter." - examples: - - Users - - CatsTable - - id: table_count - type: int - brief: "The the number of items in the `TableNames` response parameter." - examples: - - 20 + - ref: aws.dynamodb.exclusive_start_table + requirement_level: recommended + - ref: aws.dynamodb.table_count + requirement_level: recommended - ref: aws.dynamodb.limit + requirement_level: recommended - id: dynamodb.putitem brief: DynamoDB.PutItem extends: aws - prefix: aws.dynamodb type: span attributes: - ref: aws.dynamodb.table_names + requirement_level: recommended - ref: aws.dynamodb.consumed_capacity + requirement_level: recommended - ref: aws.dynamodb.item_collection_metrics + requirement_level: recommended - id: dynamodb.query brief: DynamoDB.Query extends: aws - prefix: aws.dynamodb type: span attributes: - - id: scan_forward - type: boolean - brief: "The value of the `ScanIndexForward` request parameter." + - ref: aws.dynamodb.scan_forward + requirement_level: recommended - ref: aws.dynamodb.table_names + requirement_level: recommended brief: "A single-element array with the value of the TableName request parameter." examples: - Users - ref: aws.dynamodb.consumed_capacity + requirement_level: recommended - ref: aws.dynamodb.consistent_read + requirement_level: recommended - ref: aws.dynamodb.limit + requirement_level: recommended - ref: aws.dynamodb.projection + requirement_level: recommended - ref: aws.dynamodb.attributes_to_get + requirement_level: recommended - ref: aws.dynamodb.index_name + requirement_level: recommended - ref: aws.dynamodb.select + requirement_level: recommended - id: dynamodb.scan brief: DynamoDB.Scan extends: aws - prefix: aws.dynamodb type: span attributes: - - id: segment - type: int - brief: "The value of the `Segment` request parameter." - examples: - - 10 - - id: total_segments - type: int - brief: "The value of the `TotalSegments` request parameter." - examples: - - 100 - - id: count - type: int - brief: "The value of the `Count` response parameter." - examples: - - 10 - - id: scanned_count - type: int - brief: "The value of the `ScannedCount` response parameter." - examples: - - 50 + - ref: aws.dynamodb.segment + requirement_level: recommended + - ref: aws.dynamodb.total_segments + requirement_level: recommended + - ref: aws.dynamodb.count + requirement_level: recommended + - ref: aws.dynamodb.scanned_count + requirement_level: recommended - ref: aws.dynamodb.table_names + requirement_level: recommended brief: "A single-element array with the value of the TableName request parameter." examples: - Users - ref: aws.dynamodb.consumed_capacity + requirement_level: recommended - ref: aws.dynamodb.consistent_read + requirement_level: recommended - ref: aws.dynamodb.limit + requirement_level: recommended - ref: aws.dynamodb.projection + requirement_level: recommended - ref: aws.dynamodb.attributes_to_get + requirement_level: recommended - ref: aws.dynamodb.index_name + requirement_level: recommended - ref: aws.dynamodb.select + requirement_level: recommended - id: dynamodb.updateitem brief: DynamoDB.UpdateItem extends: aws - prefix: aws.dynamodb type: span attributes: - ref: aws.dynamodb.table_names + requirement_level: recommended brief: "A single-element array with the value of the TableName request parameter." examples: - Users - ref: aws.dynamodb.consumed_capacity + requirement_level: recommended - ref: aws.dynamodb.item_collection_metrics + requirement_level: recommended - id: dynamodb.updatetable brief: DynamoDB.UpdateTable extends: aws - prefix: aws.dynamodb type: span attributes: - - id: attribute_definitions - type: string[] - brief: "The JSON-serialized value of each item in the `AttributeDefinitions` request field." - examples: - - '{ - "AttributeName": "string", - "AttributeType": "string" - }' - - id: global_secondary_index_updates - type: string[] - brief: "The JSON-serialized value of each item in the the `GlobalSecondaryIndexUpdates` request field." - examples: - - '{ - "Create": { - "IndexName": "string", - "KeySchema": [ - { - "AttributeName": "string", - "KeyType": "string" - } - ], - "Projection": { - "NonKeyAttributes": [ "string" ], - "ProjectionType": "string" - }, - "ProvisionedThroughput": { - "ReadCapacityUnits": number, - "WriteCapacityUnits": number - } - }' + - ref: aws.dynamodb.attribute_definitions + requirement_level: recommended + - ref: aws.dynamodb.global_secondary_index_updates + requirement_level: recommended - ref: aws.dynamodb.table_names + requirement_level: recommended brief: "A single-element array with the value of the TableName request parameter." examples: - Users - ref: aws.dynamodb.consumed_capacity + requirement_level: recommended - ref: aws.dynamodb.provisioned_read_capacity + requirement_level: recommended - ref: aws.dynamodb.provisioned_write_capacity + requirement_level: recommended - id: aws.s3 extends: aws - prefix: aws.s3 type: span brief: "Attributes that exist for S3 request types." attributes: - - id: bucket - type: string - brief: "The S3 bucket name the request refers to. Corresponds to the `--bucket` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations." - examples: - - some-bucket-name - note: | - The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter. - This applies to almost all S3 operations except `list-buckets`. - - id: key - type: string - brief: "The S3 object key the request refers to. Corresponds to the `--key` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations." - examples: - - someFile.yml - note: | - The `key` attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter. - This applies in particular to the following operations: - - - [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) - - [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) - - [get-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-object.html) - - [head-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/head-object.html) - - [put-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-object.html) - - [restore-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html) - - [select-object-content](https://docs.aws.amazon.com/cli/latest/reference/s3api/select-object-content.html) - - [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html) - - [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html) - - [create-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/create-multipart-upload.html) - - [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html) - - [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) - - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) - - id: copy_source - type: string - brief: "The source object (in the form `bucket`/`key`) for the copy operation." - examples: - - someFile.yml - note: | - The `copy_source` attribute applies to S3 copy operations and corresponds to the `--copy-source` parameter - of the [copy-object operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html). - This applies in particular to the following operations: - - - [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) - - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) - - id: upload_id - type: string - brief: "Upload ID that identifies the multipart upload." - examples: - - 'dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ' - note: | - The `upload_id` attribute applies to S3 multipart-upload operations and corresponds to the `--upload-id` parameter - of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) multipart operations. - This applies in particular to the following operations: - - - [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html) - - [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html) - - [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html) - - [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) - - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) - - id: delete - type: string - brief: "The delete request container that specifies the objects to be deleted." - examples: - - 'Objects=[{Key=string,VersionId=string},{Key=string,VersionId=string}],Quiet=boolean' - note: | - The `delete` attribute is only applicable to the [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) operation. - The `delete` attribute corresponds to the `--delete` parameter of the - [delete-objects operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-objects.html). - - id: part_number - type: int - brief: "The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000." - examples: - - 3456 - note: | - The `part_number` attribute is only applicable to the [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) - and [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) operations. - The `part_number` attribute corresponds to the `--part-number` parameter of the - [upload-part operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html). + - ref: aws.s3.bucket + requirement_level: recommended + - ref: aws.s3.key + requirement_level: recommended + - ref: aws.s3.copy_source + requirement_level: recommended + - ref: aws.s3.upload_id + requirement_level: recommended + - ref: aws.s3.delete + requirement_level: recommended + - ref: aws.s3.part_number + requirement_level: recommended diff --git a/model/trace/instrumentation/graphql.yml b/model/trace/instrumentation/graphql.yml index 88af65e98e..a14948da0a 100644 --- a/model/trace/instrumentation/graphql.yml +++ b/model/trace/instrumentation/graphql.yml @@ -1,32 +1,13 @@ groups: - id: graphql - prefix: graphql type: span brief: > This document defines semantic conventions to apply when instrumenting the GraphQL implementation. They map GraphQL operations to attributes on a Span. attributes: - - id: operation.name - brief: "The name of the operation being executed." - type: string - examples: 'findBookById' - - id: operation.type - brief: "The type of the operation being executed." - type: - allow_custom_values: false - members: - - id: query - value: "query" - brief: "GraphQL query" - - id: mutation - value: "mutation" - brief: "GraphQL mutation" - - id: subscription - value: "subscription" - brief: "GraphQL subscription" - examples: ['query', 'mutation', 'subscription'] - - id: document - brief: "The GraphQL document being executed." - type: string - note: The value may be sanitized to exclude sensitive information. - examples: 'query findBookById { bookById(id: ?) { name } }' + - ref: graphql.operation.name + requirement_level: recommended + - ref: graphql.operation.type + requirement_level: recommended + - ref: graphql.document + requirement_level: recommended diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index 5df3c54698..542edec127 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -1,33 +1,15 @@ groups: - id: messaging.message - prefix: messaging type: attribute_group brief: 'Semantic convention describing per-message attributes populated on messaging spans or links.' attributes: - ref: messaging.destination.name - - id: message.id - type: string - brief: 'A value used by the messaging system as an identifier for the message, represented as a string.' - examples: '452a7c7c7c7048c2f887f61572b18fc2' - - id: message.conversation_id - type: string - brief: > - The [conversation ID](#conversations) identifying the conversation to which the message belongs, - represented as a string. Sometimes called "Correlation ID". - examples: 'MyConversationId' - - id: message.payload_size_bytes - type: int - brief: > - The (uncompressed) size of the message payload in bytes. - Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. - examples: 2738 - - id: message.payload_compressed_size_bytes - type: int - brief: 'The compressed size of the message payload in bytes.' - examples: 2048 + - ref: messaging.message.id + - ref: messaging.message.conversation_id + - ref: messaging.message.envelope.size + - ref: messaging.message.body.size - id: messaging.destination - prefix: messaging.destination type: attribute_group brief: 'Semantic convention for attributes that describe messaging destination on broker' note: | @@ -40,77 +22,55 @@ groups: applies to all messages in the batch. In other cases, destination attributes may be set on links. attributes: - - id: name - type: string - brief: 'The message destination name' - note: | - Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If - the broker does not have such notion, the destination name SHOULD uniquely identify the broker. - examples: ['MyQueue', 'MyTopic'] - - id: template - type: string - brief: Low cardinality representation of the messaging destination name - note: > - 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. - examples: ['/customers/{customerId}'] - - id: temporary - type: boolean - brief: 'A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed.' - - id: anonymous - type: boolean - brief: 'A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name).' + - 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 + brief: > + Semantic convention for attributes that describe the publish messaging destination on broker. + The term Publish Destination refers to the destination the message was originally published to. + These attributes should be used on the consumer side when information about + the publish destination is available and different than the destination message are consumed from. + note: | + Publish 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_publish.name + - ref: messaging.destination_publish.anonymous - id: messaging - prefix: messaging type: span brief: > This document defines general attributes used in messaging systems. + extends: messaging.attributes.common attributes: - - id: system - type: string - requirement_level: required - brief: 'A string identifying the messaging system.' - examples: ['kafka', 'rabbitmq', 'rocketmq', 'activemq', 'AmazonSQS'] - - id: operation - type: - allow_custom_values: true - members: - - id: publish - value: "publish" - - id: receive - value: "receive" - - id: process - value: "process" + - ref: messaging.operation.type requirement_level: required - brief: > - A string identifying the kind of messaging operation as defined in the - [Operation names](#operation-names) section above. - note: If a custom value is used, it MUST be of low cardinality. - - id: batch.message_count - type: int - brief: The number of messages sent, received, or processed in the scope of the batching operation. + - ref: messaging.operation.name + requirement_level: + recommended: If the operation is not sufficiently described by `messaging.operation.type`. + - ref: messaging.batch.message_count requirement_level: conditionally_required: If the span describes an operation on a batch of messages. - note: > - 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. - examples: [0, 1, 2] - - id: client_id - type: string + - ref: messaging.client_id requirement_level: recommended: If a client id is available - brief: > - A unique identifier for the client that consumes or produces a message. - examples: ['client-5', 'myhost@8742@s8083jm'] - 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. + - ref: messaging.destination.partition.id + requirement_level: + recommended: When applicable. - ref: messaging.destination.template requirement_level: conditionally_required: > @@ -123,169 +83,154 @@ groups: requirement_level: conditionally_required: If value is `true`. When missing, the value is assumed to be `false`. - ref: messaging.message.id - requirement_level: - recommended: Only for spans that represent an operation on a single message. - ref: messaging.message.conversation_id + - ref: messaging.message.envelope.size + - ref: messaging.message.body.size + - ref: network.peer.address + brief: Peer address of the messaging intermediary node where the operation was performed. requirement_level: - recommended: Only if span represents operation on a single message. - - ref: messaging.message.payload_size_bytes - requirement_level: - recommended: Only if span represents operation on a single message. - - ref: messaging.message.payload_compressed_size_bytes - requirement_level: - recommended: Only if span represents operation on a single message. - - ref: server.address + recommended: If applicable for this messaging system. note: > - This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. - requirement_level: - conditionally_required: If available. - - ref: server.socket.address - tag: connection-level - - ref: server.socket.port - tag: connection-level - - ref: network.transport - tag: connection-level - - ref: network.type - tag: connection-level - - ref: server.socket.domain - tag: connection-level + 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. + - ref: network.peer.port + brief: Peer port of the messaging intermediary node where the operation was performed. requirement_level: - recommended: If different than `server.address` and if `server.socket.address` is set. - - ref: network.protocol.name - examples: ['amqp', 'mqtt'] - - ref: network.protocol.version + recommended: if and only if `network.peer.address` is set. - - id: messaging.rabbitmq - prefix: messaging.rabbitmq + - id: messaging.tech_specific.network.attributes type: attribute_group + brief: Attributes that describe messaging operation along with network information. extends: messaging + attributes: + - ref: network.peer.address + requirement_level: recommended + note: > + If an operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. + - ref: network.peer.port + requirement_level: recommended + + - id: messaging.rabbitmq + type: attribute_group + extends: messaging.tech_specific.network.attributes brief: > Attributes for RabbitMQ attributes: - - id: destination.routing_key - type: string + - ref: messaging.rabbitmq.destination.routing_key requirement_level: conditionally_required: If not empty. - brief: > - RabbitMQ message routing key. - examples: 'myKey' + tag: tech-specific + - ref: messaging.rabbitmq.message.delivery_tag + requirement_level: + conditionally_required: When available. + tag: tech-specific + - ref: network.peer.address + tag: tech-specific + - ref: network.peer.port + tag: tech-specific - id: messaging.kafka - prefix: messaging.kafka type: attribute_group extends: messaging brief: > Attributes for Apache Kafka attributes: - - id: message.key - type: string - brief: > - 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. - note: > - 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. - examples: 'myKey' - - id: consumer.group - type: string - brief: > - Name of the Kafka Consumer Group that is handling the message. - Only applies to consumers, not producers. - examples: 'my-group' - - id: destination.partition - type: int - brief: > - Partition the message is sent to. - examples: 2 - - id: message.offset - type: int - brief: > - The offset of a record in the corresponding Kafka partition. - examples: 42 - - id: message.tombstone - type: boolean + - 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 + tag: tech-specific + - ref: messaging.kafka.message.key + tag: tech-specific + - ref: messaging.kafka.consumer.group + tag: tech-specific + - ref: messaging.kafka.message.offset + tag: tech-specific + - ref: messaging.kafka.message.tombstone requirement_level: conditionally_required: If value is `true`. When missing, the value is assumed to be `false`. - brief: 'A boolean that is true if the message is a tombstone.' + tag: tech-specific - id: messaging.rocketmq - prefix: messaging.rocketmq type: attribute_group extends: messaging brief: > Attributes for Apache RocketMQ attributes: - - id: namespace - type: string + - ref: messaging.rocketmq.namespace requirement_level: required - brief: > - Namespace of RocketMQ resources, resources in different namespaces are individual. - examples: 'myNamespace' - - id: client_group - type: string + tag: tech-specific + - ref: messaging.rocketmq.client_group requirement_level: required - brief: > - Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. - examples: 'myConsumerGroup' - - id: message.delivery_timestamp - type: int + tag: tech-specific + - ref: messaging.rocketmq.message.delivery_timestamp requirement_level: conditionally_required: If the message type is delay and delay time level is not specified. - brief: > - The timestamp in milliseconds that the delay message is expected to be delivered to consumer. - examples: 1665987217045 - - id: message.delay_time_level - type: int + tag: tech-specific + - ref: messaging.rocketmq.message.delay_time_level requirement_level: conditionally_required: If the message type is delay and delivery timestamp is not specified. - brief: > - The delay time level for delay message, which determines the message delay time. - examples: 3 - - id: message.group - type: string + tag: tech-specific + - ref: messaging.rocketmq.message.group requirement_level: conditionally_required: If the message type is FIFO. + tag: tech-specific + - ref: messaging.rocketmq.message.type + tag: tech-specific + - ref: messaging.rocketmq.message.tag + tag: tech-specific + - ref: messaging.rocketmq.message.keys + tag: tech-specific + - ref: messaging.rocketmq.consumption_model + tag: tech-specific + - id: messaging.gcp_pubsub + type: attribute_group + stability: experimental + extends: messaging + brief: > + Attributes for Google Cloud Pub/Sub + attributes: + - ref: messaging.gcp_pubsub.message.ordering_key + tag: tech-specific-gcp-pubsub + requirement_level: + conditionally_required: If the message type has an ordering key set. + - ref: messaging.gcp_pubsub.message.delivery_attempt + tag: tech-specific-gcp-pubsub + - ref: messaging.gcp_pubsub.message.ack_deadline + tag: tech-specific-gcp-pubsub + - ref: messaging.gcp_pubsub.message.ack_id + tag: tech-specific-gcp-pubsub + - id: messaging.servicebus + type: attribute_group + extends: messaging + brief: > + Attributes for Azure Service Bus + attributes: + - 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`. + - id: messaging.eventhubs + type: attribute_group + extends: messaging + brief: > + Attributes for Azure Event Hubs + attributes: + - ref: messaging.destination.partition.id brief: > - 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. - examples: 'myMessageGroup' - - id: message.type - type: - allow_custom_values: false - members: - - id: normal - value: 'normal' - brief: "Normal message" - - id: fifo - value: 'fifo' - brief: 'FIFO message' - - id: delay - value: 'delay' - brief: 'Delay message' - - id: transaction - value: 'transaction' - brief: 'Transaction message' - brief: > - Type of message. - - id: message.tag - type: string - brief: > - The secondary classifier of message besides topic. - examples: tagA - - id: message.keys - type: string[] - brief: > - Key(s) of message, another way to mark message besides message id. - examples: ['keyA', 'keyB'] - - id: consumption_model - type: - allow_custom_values: false - members: - - id: clustering - value: 'clustering' - brief: 'Clustering consumption model' - - id: broadcasting - value: 'broadcasting' - brief: 'Broadcasting consumption model' - brief: > - Model of message consumption. This only applies to consumer spans. + String representation of the partition id messages are sent to or received from, unique within the Event Hub. + requirement_level: + conditionally_required: If available. + - ref: messaging.eventhubs.message.enqueued_time + - ref: messaging.eventhubs.consumer.group + requirement_level: + conditionally_required: If not default ("$Default"). diff --git a/model/trace/rpc.yaml b/model/trace/rpc.yaml index d2aab9a5ed..d578c6ba6a 100644 --- a/model/trace/rpc.yaml +++ b/model/trace/rpc.yaml @@ -5,56 +5,16 @@ groups: brief: 'This document defines semantic conventions for remote procedure calls.' events: [rpc.message] attributes: - - id: system + - ref: rpc.system requirement_level: required - brief: 'A string identifying the remoting system. See below for a list of well-known identifiers.' - type: - allow_custom_values: true - members: - - id: grpc - value: 'grpc' - brief: 'gRPC' - - id: java_rmi - value: 'java_rmi' - brief: 'Java RMI' - - id: dotnet_wcf - value: 'dotnet_wcf' - brief: '.NET WCF' - - id: apache_dubbo - value: 'apache_dubbo' - brief: 'Apache Dubbo' - - id: connect_rpc - value: 'connect_rpc' - brief: 'Connect RPC' - - id: service - type: string + - ref: rpc.service requirement_level: recommended - brief: 'The full (logical) name of the service being called, including its package name, if applicable.' - note: > - This is the logical name of the service from the RPC interface perspective, - which can be different from the name of any implementing class. - The `code.namespace` attribute may be used to store the latter - (despite the attribute name, it may include a class name; - e.g., class with method actually executing the call on the server side, - RPC client stub class on the client side). - examples: "myservice.EchoService" - - id: method - type: string + - ref: rpc.method requirement_level: recommended - brief: 'The name of the (logical) method being called, must be equal to the $method part in the span name.' - note: > - This is the logical name of the method from the RPC interface perspective, - which can be different from the name of any implementing method/function. - The `code.function` attribute may be used to store the latter - (e.g., method actually executing the call on the server side, - RPC client stub method on the client side). - examples: "exampleMethod" - - ref: server.socket.address - - ref: server.socket.port - requirement_level: - recommended: If different than `server.port` and if `server.socket.address` is set. - ref: network.transport + requirement_level: recommended - ref: network.type + requirement_level: recommended - ref: server.address requirement_level: required brief: > @@ -65,97 +25,53 @@ groups: `server.address` to the IP address provided in the host component. - ref: server.port requirement_level: - conditionally_required: See below - constraints: - - any_of: - - server.socket.address - - server.address + conditionally_required: if the port is supported by the network transport used for communication. - id: rpc.client type: span brief: 'This document defines semantic conventions for remote procedure call client spans.' extends: rpc attributes: - - ref: server.socket.domain + - ref: network.peer.address + requirement_level: recommended + - ref: network.peer.port requirement_level: - recommended: If different than `server.address` and if `server.socket.address` is set. + recommended: If `network.peer.address` is set. - id: rpc.server - prefix: rpc type: span extends: rpc span_kind: server brief: 'Semantic Convention for RPC server spans' attributes: - ref: client.address + requirement_level: recommended - ref: client.port - - ref: client.socket.address - - ref: client.socket.port + requirement_level: recommended + - ref: network.peer.address + requirement_level: recommended + - ref: network.peer.port + requirement_level: + recommended: If `network.peer.address` is set. - ref: network.transport + requirement_level: recommended - ref: network.type + requirement_level: recommended - id: rpc.grpc - prefix: rpc.grpc type: span extends: rpc brief: 'Tech-specific attributes for gRPC.' attributes: - - id: status_code - type: - members: - - id: ok - brief: OK - value: 0 - - id: cancelled - brief: CANCELLED - value: 1 - - id: unknown - brief: UNKNOWN - value: 2 - - id: invalid_argument - brief: INVALID_ARGUMENT - value: 3 - - id: deadline_exceeded - brief: DEADLINE_EXCEEDED - value: 4 - - id: not_found - brief: NOT_FOUND - value: 5 - - id: already_exists - brief: ALREADY_EXISTS - value: 6 - - id: permission_denied - brief: PERMISSION_DENIED - value: 7 - - id: resource_exhausted - brief: RESOURCE_EXHAUSTED - value: 8 - - id: failed_precondition - brief: FAILED_PRECONDITION - value: 9 - - id: aborted - brief: ABORTED - value: 10 - - id: out_of_range - brief: OUT_OF_RANGE - value: 11 - - id: unimplemented - brief: UNIMPLEMENTED - value: 12 - - id: internal - brief: INTERNAL - value: 13 - - id: unavailable - brief: UNAVAILABLE - value: 14 - - id: data_loss - brief: DATA_LOSS - value: 15 - - id: unauthenticated - brief: UNAUTHENTICATED - value: 16 + - ref: rpc.grpc.status_code + tag: grpc-tech-specific requirement_level: required - brief: "The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request." + - ref: rpc.grpc.request.metadata + tag: grpc-tech-specific + requirement_level: opt_in + - ref: rpc.grpc.response.metadata + tag: grpc-tech-specific + requirement_level: opt_in - id: rpc.jsonrpc prefix: rpc.jsonrpc @@ -163,101 +79,53 @@ groups: extends: rpc brief: 'Tech-specific attributes for [JSON RPC](https://www.jsonrpc.org/).' attributes: - - id: version - type: string + - ref: rpc.jsonrpc.version + tag: jsonrpc-tech-specific requirement_level: conditionally_required: If other than the default version (`1.0`) - brief: "Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 does not specify this, the value can be omitted." - examples: ['2.0', '1.0'] - - id: request_id - type: string - brief: > - `id` property of request or response. - Since protocol allows id to be int, string, `null` or missing (for notifications), - value is expected to be cast to string for simplicity. - Use empty string in case of `null` value. Omit entirely if this is a notification. - examples: ['10', 'request-7', ''] - - id: error_code - type: int + - ref: rpc.jsonrpc.request_id + tag: jsonrpc-tech-specific + requirement_level: recommended + - ref: rpc.jsonrpc.error_code + tag: jsonrpc-tech-specific requirement_level: conditionally_required: If response is not successful. - brief: "`error.code` property of response if it is an error response." - examples: [-32700, 100] - - id: error_message - type: string - brief: "`error.message` property of response if it is an error response." - examples: ['Parse error', 'User already exists'] + - ref: rpc.jsonrpc.error_message + tag: jsonrpc-tech-specific + requirement_level: recommended - ref: rpc.method + tag: jsonrpc-tech-specific requirement_level: required note: > This is always required for jsonrpc. See the note in the general RPC conventions for more information. - id: rpc.message - prefix: "message" # TODO: Change the prefix to rpc.message? + prefix: rpc.message type: event brief: "RPC received/sent message." attributes: - - id: type - type: - members: - - id: sent - value: "SENT" - - id: received - value: "RECEIVED" - brief: "Whether this is a received or sent message." - - id: id - type: int - brief: "MUST be calculated as two different counters starting from `1` one for sent messages and one for received message." - note: "This way we guarantee that the values will be consistent between different implementations." - - id: compressed_size - type: int - brief: "Compressed size of the message in bytes." - - id: uncompressed_size - type: int - brief: "Uncompressed size of the message in bytes." + - ref: rpc.message.type + requirement_level: recommended + - ref: rpc.message.id + requirement_level: recommended + - ref: rpc.message.compressed_size + requirement_level: recommended + - ref: rpc.message.uncompressed_size + requirement_level: recommended - id: rpc.connect_rpc - prefix: rpc.connect_rpc type: span extends: rpc brief: 'Tech-specific attributes for Connect RPC.' attributes: - - id: error_code - type: - members: - - id: cancelled - value: cancelled - - id: unknown - value: unknown - - id: invalid_argument - value: invalid_argument - - id: deadline_exceeded - value: deadline_exceeded - - id: not_found - value: not_found - - id: already_exists - value: already_exists - - id: permission_denied - value: permission_denied - - id: resource_exhausted - value: resource_exhausted - - id: failed_precondition - value: failed_precondition - - id: aborted - value: aborted - - id: out_of_range - value: out_of_range - - id: unimplemented - value: unimplemented - - id: internal - value: internal - - id: unavailable - value: unavailable - - id: data_loss - value: data_loss - - id: unauthenticated - value: unauthenticated + - ref: rpc.connect_rpc.error_code + tag: connect_rpc-tech-specific requirement_level: conditionally_required: If response is not successful and if error code available. - brief: "The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values." + - ref: rpc.connect_rpc.request.metadata + tag: connect_rpc-tech-specific + requirement_level: opt_in + - ref: rpc.connect_rpc.response.metadata + tag: connect_rpc-tech-specific + requirement_level: opt_in diff --git a/model/trace/trace-exception.yaml b/model/trace/trace-exception.yaml index a11082ebd9..32c53f4b30 100644 --- a/model/trace/trace-exception.yaml +++ b/model/trace/trace-exception.yaml @@ -7,32 +7,10 @@ groups: report a single exception associated with a span. attributes: - ref: exception.type + requirement_level: + conditionally_required: Required if `exception.message` is not set, recommended otherwise. - ref: exception.message + requirement_level: + conditionally_required: Required if `exception.type` is not set, recommended otherwise. - ref: exception.stacktrace - - id: escaped - type: boolean - brief: > - SHOULD be set to true if the exception event is recorded at a point where - it is known that the exception is escaping the scope of the span. - note: |- - An exception is considered to have escaped (or left) the scope of a span, - if that span is ended while the exception is still logically "in flight". - This may be actually "in flight" in some languages (e.g. if the exception - is passed to a Context manager's `__exit__` method in Python) but will - usually be caught at the point of recording the exception in most languages. - - It is usually not possible to determine at the point where an exception is thrown - whether it will escape the scope of a span. - However, it is trivial to know that an exception - will escape, if one checks for an active exception just before ending the span, - as done in the [example above](#recording-an-exception). - - It follows that an exception may still escape the scope of the span - even if the `exception.escaped` attribute was not set or set to false, - since the event might have been recorded at a time where it was not - clear whether the exception will escape. - - constraints: - - any_of: - - "exception.type" - - "exception.message" + - ref: exception.escaped diff --git a/model/url.yaml b/model/url.yaml index 6e839fc394..bb27dc4e6d 100644 --- a/model/url.yaml +++ b/model/url.yaml @@ -4,36 +4,10 @@ groups: type: attribute_group prefix: url attributes: - - id: scheme - type: string - brief: 'The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol.' - examples: ["https", "ftp", "telnet"] - - id: full - type: string - brief: Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) - note: > - For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment - is not transmitted over HTTP, but if it is known, it should be included nevertheless. - - `url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. - In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`. - - `url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) - and SHOULD NOT be validated or modified except for sanitizing purposes. - examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv', '//localhost'] + - ref: url.scheme + - ref: url.full tag: sensitive-information - - id: path - type: string - brief: 'The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component' - examples: ['/search'] - note: When missing, the value is assumed to be `/` - - id: query - type: string - brief: 'The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component' - examples: ["q=OpenTelemetry"] - note: Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. + - ref: url.path + - ref: url.query tag: sensitive-information - - id: fragment - type: string - brief: 'The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component' - examples: ["SemConv"] + - ref: url.fragment diff --git a/model/user-agent.yaml b/model/user-agent.yaml deleted file mode 100644 index 2f43b1af3e..0000000000 --- a/model/user-agent.yaml +++ /dev/null @@ -1,10 +0,0 @@ -groups: - - id: attributes.user_agent - type: attribute_group - brief: "Describes user-agent attributes." - prefix: user_agent - attributes: - - id: original - type: string - brief: 'Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client.' - examples: ['CERN-LineMode/2.15 libwww/2.17b3'] diff --git a/package.json b/package.json index d51304272a..dd8bc20cb2 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,7 @@ "devDependencies": { "gulp": "^4.0.2", "js-yaml": "^4.1.0", - "markdown-link-check": "3.10.3", + "markdown-link-check": "3.11.2", "markdown-toc": "^1.2.0", "markdownlint": "^0.29.0", "markdownlint-cli": "0.31.0", diff --git a/schema-next.yaml b/schema-next.yaml index 37d35efc84..e344c34056 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -1,7 +1,291 @@ file_format: 1.1.0 -schema_url: https://opentelemetry.io/schemas/1.21.0 +schema_url: https://opentelemetry.io/schemas/next versions: next: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/966 + - rename_metrics: + db.client.connections.usage: db.client.connection.count + db.client.connections.idle.max: db.client.connection.idle.max + db.client.connections.idle.min: db.client.connection.idle.min + db.client.connections.max: db.client.connection.max + db.client.connections.pending_requests: db.client.connection.pending_requests + db.client.connections.timeouts: db.client.connection.timeouts + # https://github.com/open-telemetry/semantic-conventions/pull/909 + - rename_attributes: + attribute_map: + state: db.client.connections.state + apply_to_metrics: + - db.client.connections.usage + - rename_attributes: + attribute_map: + pool.name: db.client.connections.pool.name + apply_to_metrics: + - db.client.connections.usage + - db.client.connections.idle.max + - db.client.connections.idle.min + - db.client.connections.max + - db.client.connections.pending_requests + - db.client.connections.timeouts + - db.client.connections.create_time + - db.client.connections.wait_time + - db.client.connections.use_time + + 1.25.0: + spans: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/911 + - rename_attributes: + attribute_map: + db.name: db.namespace + # https://github.com/open-telemetry/semantic-conventions/pull/870 + - rename_attributes: + attribute_map: + db.sql.table: db.collection.name + db.mongodb.collection: db.collection.name + db.cosmosdb.container: db.collection.name + db.cassandra.table: db.collection.name + # https://github.com/open-telemetry/semantic-conventions/pull/798 + - rename_attributes: + attribute_map: + messaging.kafka.destination.partition: messaging.destination.partition.id + # https://github.com/open-telemetry/semantic-conventions/pull/875 + - rename_attributes: + attribute_map: + db.operation: db.operation.name + # https://github.com/open-telemetry/semantic-conventions/pull/913 + - rename_attributes: + attribute_map: + messaging.operation: messaging.operation.type + # https://github.com/open-telemetry/semantic-conventions/pull/866 + - rename_attributes: + attribute_map: + db.statement: db.query.text + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/484 + - rename_attributes: + attribute_map: + system.processes.status: system.process.status + apply_to_metrics: + - system.processes.count + - rename_metrics: + system.processes.count: system.process.count + system.processes.created: system.process.created + # https://github.com/open-telemetry/semantic-conventions/pull/625 + - rename_attributes: + attribute_map: + container.labels: container.label + k8s.pod.labels: k8s.pod.label + # https://github.com/open-telemetry/semantic-conventions/pull/330 + - rename_metrics: + process.threads: process.thread.count + process.open_file_descriptors: process.open_file_descriptor.count + - rename_attributes: + attribute_map: + state: process.cpu.state + apply_to_metrics: + - process.cpu.time + - process.cpu.utilization + - rename_attributes: + attribute_map: + direction: disk.io.direction + apply_to_metrics: + - process.disk.io + - rename_attributes: + attribute_map: + type: process.context_switch_type + apply_to_metrics: + - process.context_switches + - rename_attributes: + attribute_map: + direction: network.io.direction + apply_to_metrics: + - process.network.io + - rename_attributes: + attribute_map: + type: process.paging.fault_type + apply_to_metrics: + - process.paging.faults + all: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/854 + - rename_attributes: + attribute_map: + message.type: rpc.message.type + message.id: rpc.message.id + message.compressed_size: rpc.message.compressed_size + message.uncompressed_size: rpc.message.uncompressed_size + + 1.24.0: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/536 + - rename_metrics: + jvm.memory.usage: jvm.memory.used + jvm.memory.usage_after_last_gc: jvm.memory.used_after_last_gc + # https://github.com/open-telemetry/semantic-conventions/pull/530 + - rename_attributes: + attribute_map: + system.network.io.direction: network.io.direction + system.disk.io.direction: disk.io.direction + 1.23.1: + 1.23.0: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/20 + - rename_attributes: + attribute_map: + thread.daemon: jvm.thread.daemon + apply_to_metrics: + - jvm.thread.count + 1.22.0: + spans: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/229 + - rename_attributes: + attribute_map: + messaging.message.payload_size_bytes: messaging.message.body.size + # https://github.com/open-telemetry/opentelemetry-specification/pull/374 + - rename_attributes: + attribute_map: + http.resend_count: http.request.resend_count + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/224 + - rename_metrics: + http.client.duration: http.client.request.duration + http.server.duration: http.server.request.duration + # https://github.com/open-telemetry/semantic-conventions/pull/241 + - rename_metrics: + process.runtime.jvm.memory.usage: jvm.memory.usage + process.runtime.jvm.memory.committed: jvm.memory.committed + process.runtime.jvm.memory.limit: jvm.memory.limit + process.runtime.jvm.memory.usage_after_last_gc: jvm.memory.usage_after_last_gc + process.runtime.jvm.gc.duration: jvm.gc.duration + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.threads.count: jvm.thread.count + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.classes.loaded: jvm.class.loaded + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.classes.unloaded: jvm.class.unloaded + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + # and https://github.com/open-telemetry/semantic-conventions/pull/60 + process.runtime.jvm.classes.current_loaded: jvm.class.count + process.runtime.jvm.cpu.time: jvm.cpu.time + process.runtime.jvm.cpu.recent_utilization: jvm.cpu.recent_utilization + process.runtime.jvm.memory.init: jvm.memory.init + process.runtime.jvm.system.cpu.utilization: jvm.system.cpu.utilization + process.runtime.jvm.system.cpu.load_1m: jvm.system.cpu.load_1m + # https://github.com/open-telemetry/semantic-conventions/pull/253 + process.runtime.jvm.buffer.usage: jvm.buffer.memory.usage + # https://github.com/open-telemetry/semantic-conventions/pull/253 + process.runtime.jvm.buffer.limit: jvm.buffer.memory.limit + process.runtime.jvm.buffer.count: jvm.buffer.count + # https://github.com/open-telemetry/semantic-conventions/pull/20 + - rename_attributes: + attribute_map: + type: jvm.memory.type + pool: jvm.memory.pool.name + apply_to_metrics: + - jvm.memory.usage + - jvm.memory.committed + - jvm.memory.limit + - jvm.memory.usage_after_last_gc + - jvm.memory.init + - rename_attributes: + attribute_map: + name: jvm.gc.name + action: jvm.gc.action + apply_to_metrics: + - jvm.gc.duration + - rename_attributes: + attribute_map: + daemon: thread.daemon + apply_to_metrics: + - jvm.threads.count + - rename_attributes: + attribute_map: + pool: jvm.buffer.pool.name + apply_to_metrics: + - jvm.buffer.memory.usage + - jvm.buffer.memory.limit + - jvm.buffer.count + # https://github.com/open-telemetry/semantic-conventions/pull/89 + - rename_attributes: + attribute_map: + state: system.cpu.state + cpu: system.cpu.logical_number + apply_to_metrics: + - system.cpu.time + - system.cpu.utilization + - rename_attributes: + attribute_map: + state: system.memory.state + apply_to_metrics: + - system.memory.usage + - system.memory.utilization + - rename_attributes: + attribute_map: + state: system.paging.state + apply_to_metrics: + - system.paging.usage + - system.paging.utilization + - rename_attributes: + attribute_map: + type: system.paging.type + direction: system.paging.direction + apply_to_metrics: + - system.paging.faults + - system.paging.operations + - rename_attributes: + attribute_map: + device: system.device + direction: system.disk.direction + apply_to_metrics: + - system.disk.io + - system.disk.operations + - system.disk.io_time + - system.disk.operation_time + - system.disk.merged + - rename_attributes: + attribute_map: + device: system.device + state: system.filesystem.state + type: system.filesystem.type + mode: system.filesystem.mode + mountpoint: system.filesystem.mountpoint + apply_to_metrics: + - system.filesystem.usage + - system.filesystem.utilization + - rename_attributes: + attribute_map: + device: system.device + direction: system.network.direction + protocol: network.protocol + state: system.network.state + apply_to_metrics: + - system.network.dropped + - system.network.packets + - system.network.errors + - system.network.io + - system.network.connections + - rename_attributes: + attribute_map: + status: system.processes.status + apply_to_metrics: + - system.processes.count + # https://github.com/open-telemetry/semantic-conventions/pull/247 + - rename_metrics: + http.server.request.size: http.server.request.body.size + http.server.response.size: http.server.response.body.size + resources: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/178 + - rename_attributes: + attribute_map: + telemetry.auto.version: telemetry.distro.version 1.21.0: spans: changes: diff --git a/schemas/1.22.0 b/schemas/1.22.0 new file mode 100644 index 0000000000..c5a7f93a74 --- /dev/null +++ b/schemas/1.22.0 @@ -0,0 +1,280 @@ +file_format: 1.1.0 +schema_url: https://opentelemetry.io/schemas/1.22.0 +versions: + 1.22.0: + spans: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/229 + - rename_attributes: + attribute_map: + messaging.message.payload_size_bytes: messaging.message.body.size + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/224 + - rename_metrics: + http.client.duration: http.client.request.duration + http.server.duration: http.server.request.duration + # https://github.com/open-telemetry/semantic-conventions/pull/241 + - rename_metrics: + process.runtime.jvm.memory.usage: jvm.memory.usage + process.runtime.jvm.memory.committed: jvm.memory.committed + process.runtime.jvm.memory.limit: jvm.memory.limit + process.runtime.jvm.memory.usage_after_last_gc: jvm.memory.usage_after_last_gc + process.runtime.jvm.gc.duration: jvm.gc.duration + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.threads.count: jvm.thread.count + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.classes.loaded: jvm.class.loaded + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.classes.unloaded: jvm.class.unloaded + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + # and https://github.com/open-telemetry/semantic-conventions/pull/60 + process.runtime.jvm.classes.current_loaded: jvm.class.count + process.runtime.jvm.cpu.time: jvm.cpu.time + process.runtime.jvm.cpu.recent_utilization: jvm.cpu.recent_utilization + process.runtime.jvm.memory.init: jvm.memory.init + process.runtime.jvm.system.cpu.utilization: jvm.system.cpu.utilization + process.runtime.jvm.system.cpu.load_1m: jvm.system.cpu.load_1m + # https://github.com/open-telemetry/semantic-conventions/pull/253 + process.runtime.jvm.buffer.usage: jvm.buffer.memory.usage + # https://github.com/open-telemetry/semantic-conventions/pull/253 + process.runtime.jvm.buffer.limit: jvm.buffer.memory.limit + process.runtime.jvm.buffer.count: jvm.buffer.count + # https://github.com/open-telemetry/semantic-conventions/pull/20 + - rename_attributes: + attribute_map: + type: jvm.memory.type + pool: jvm.memory.pool.name + apply_to_metrics: + - jvm.memory.usage + - jvm.memory.committed + - jvm.memory.limit + - jvm.memory.usage_after_last_gc + - jvm.memory.init + - rename_attributes: + attribute_map: + name: jvm.gc.name + action: jvm.gc.action + apply_to_metrics: + - jvm.gc.duration + - rename_attributes: + attribute_map: + daemon: thread.daemon + apply_to_metrics: + - jvm.threads.count + - rename_attributes: + attribute_map: + pool: jvm.buffer.pool.name + apply_to_metrics: + - jvm.buffer.usage + - jvm.buffer.limit + - jvm.buffer.count + # https://github.com/open-telemetry/semantic-conventions/pull/89 + - rename_attributes: + attribute_map: + state: system.cpu.state + cpu: system.cpu.logical_number + apply_to_metrics: + - system.cpu.time + - system.cpu.utilization + - rename_attributes: + attribute_map: + state: system.memory.state + apply_to_metrics: + - system.memory.usage + - system.memory.utilization + - rename_attributes: + attribute_map: + state: system.paging.state + apply_to_metrics: + - system.paging.usage + - system.paging.utilization + - rename_attributes: + attribute_map: + type: system.paging.type + direction: system.paging.direction + apply_to_metrics: + - system.paging.faults + - system.paging.operations + - rename_attributes: + attribute_map: + device: system.device + direction: system.disk.direction + apply_to_metrics: + - system.disk.io + - system.disk.operations + - system.disk.io_time + - system.disk.operation_time + - system.disk.merged + - rename_attributes: + attribute_map: + device: system.device + state: system.filesystem.state + type: system.filesystem.type + mode: system.filesystem.mode + mountpoint: system.filesystem.mountpoint + apply_to_metrics: + - system.filesystem.usage + - system.filesystem.utilization + - rename_attributes: + attribute_map: + device: system.device + direction: system.network.direction + protocol: network.protocol + state: system.network.state + apply_to_metrics: + - system.network.dropped + - system.network.packets + - system.network.errors + - system.network.io + - system.network.connections + - rename_attributes: + attribute_map: + status: system.processes.status + apply_to_metrics: + - system.processes.count + # https://github.com/open-telemetry/semantic-conventions/pull/247 + - rename_metrics: + http.server.request.size: http.server.request.body.size + http.server.response.size: http.server.response.body.size + resources: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/178 + - rename_attributes: + attribute_map: + telemetry.auto.version: telemetry.distro.version + 1.21.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3336 + - rename_attributes: + attribute_map: + messaging.kafka.client_id: messaging.client_id + messaging.rocketmq.client_id: messaging.client_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3402 + - rename_attributes: + attribute_map: + # net.peer.(name|port) attributes were usually populated on client side + # so they should be usually translated to server.(address|port) + # net.host.* attributes were only populated on server side + net.host.name: server.address + net.host.port: server.port + # was only populated on client side + net.sock.peer.name: server.socket.domain + # net.sock.peer.(addr|port) mapping is not possible + # since they applied to both client and server side + # were only populated on server side + net.sock.host.addr: server.socket.address + net.sock.host.port: server.socket.port + http.client_ip: client.address + # https://github.com/open-telemetry/opentelemetry-specification/pull/3426 + - rename_attributes: + attribute_map: + net.protocol.name: network.protocol.name + net.protocol.version: network.protocol.version + net.host.connection.type: network.connection.type + net.host.connection.subtype: network.connection.subtype + net.host.carrier.name: network.carrier.name + net.host.carrier.mcc: network.carrier.mcc + net.host.carrier.mnc: network.carrier.mnc + net.host.carrier.icc: network.carrier.icc + # https://github.com/open-telemetry/opentelemetry-specification/pull/3355 + - rename_attributes: + attribute_map: + http.method: http.request.method + http.status_code: http.response.status_code + http.scheme: url.scheme + http.url: url.full + http.request_content_length: http.request.body.size + http.response_content_length: http.response.body.size + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/53 + - rename_metrics: + process.runtime.jvm.cpu.utilization: process.runtime.jvm.cpu.recent_utilization + 1.20.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3272 + - rename_attributes: + attribute_map: + net.app.protocol.name: net.protocol.name + net.app.protocol.version: net.protocol.version + 1.19.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3209 + - rename_attributes: + attribute_map: + faas.execution: faas.invocation_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3188 + - rename_attributes: + attribute_map: + faas.id: cloud.resource_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3190 + - rename_attributes: + attribute_map: + http.user_agent: user_agent.original + resources: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3190 + - rename_attributes: + attribute_map: + browser.user_agent: user_agent.original + 1.18.0: + 1.17.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2957 + - rename_attributes: + attribute_map: + messaging.consumer_id: messaging.consumer.id + messaging.protocol: net.app.protocol.name + messaging.protocol_version: net.app.protocol.version + messaging.destination: messaging.destination.name + messaging.temp_destination: messaging.destination.temporary + messaging.destination_kind: messaging.destination.kind + messaging.message_id: messaging.message.id + messaging.conversation_id: messaging.message.conversation_id + messaging.message_payload_size_bytes: messaging.message.payload_size_bytes + messaging.message_payload_compressed_size_bytes: messaging.message.payload_compressed_size_bytes + messaging.rabbitmq.routing_key: messaging.rabbitmq.destination.routing_key + messaging.kafka.message_key: messaging.kafka.message.key + messaging.kafka.partition: messaging.kafka.destination.partition + messaging.kafka.tombstone: messaging.kafka.message.tombstone + messaging.rocketmq.message_type: messaging.rocketmq.message.type + messaging.rocketmq.message_tag: messaging.rocketmq.message.tag + messaging.rocketmq.message_keys: messaging.rocketmq.message.keys + messaging.kafka.consumer_group: messaging.kafka.consumer.group + 1.16.0: + 1.15.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2743 + - rename_attributes: + attribute_map: + http.retry_count: http.resend_count + 1.14.0: + 1.13.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2614 + - rename_attributes: + attribute_map: + net.peer.ip: net.sock.peer.addr + net.host.ip: net.sock.host.addr + 1.12.0: + 1.11.0: + 1.10.0: + 1.9.0: + 1.8.0: + spans: + changes: + - rename_attributes: + attribute_map: + db.cassandra.keyspace: db.name + db.hbase.namespace: db.name + 1.7.0: + 1.6.1: + 1.5.0: + 1.4.0: diff --git a/schemas/1.23.0 b/schemas/1.23.0 new file mode 100644 index 0000000000..a6e29937d0 --- /dev/null +++ b/schemas/1.23.0 @@ -0,0 +1,293 @@ +file_format: 1.1.0 +schema_url: https://opentelemetry.io/schemas/1.23.0 +versions: + 1.23.0: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/20 + - rename_attributes: + attribute_map: + thread.daemon: jvm.thread.daemon + apply_to_metrics: + - jvm.thread.count + 1.22.0: + spans: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/229 + - rename_attributes: + attribute_map: + messaging.message.payload_size_bytes: messaging.message.body.size + # https://github.com/open-telemetry/opentelemetry-specification/pull/374 + - rename_attributes: + attribute_map: + http.resend_count: http.request.resend_count + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/224 + - rename_metrics: + http.client.duration: http.client.request.duration + http.server.duration: http.server.request.duration + # https://github.com/open-telemetry/semantic-conventions/pull/241 + - rename_metrics: + process.runtime.jvm.memory.usage: jvm.memory.usage + process.runtime.jvm.memory.committed: jvm.memory.committed + process.runtime.jvm.memory.limit: jvm.memory.limit + process.runtime.jvm.memory.usage_after_last_gc: jvm.memory.usage_after_last_gc + process.runtime.jvm.gc.duration: jvm.gc.duration + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.threads.count: jvm.thread.count + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.classes.loaded: jvm.class.loaded + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.classes.unloaded: jvm.class.unloaded + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + # and https://github.com/open-telemetry/semantic-conventions/pull/60 + process.runtime.jvm.classes.current_loaded: jvm.class.count + process.runtime.jvm.cpu.time: jvm.cpu.time + process.runtime.jvm.cpu.recent_utilization: jvm.cpu.recent_utilization + process.runtime.jvm.memory.init: jvm.memory.init + process.runtime.jvm.system.cpu.utilization: jvm.system.cpu.utilization + process.runtime.jvm.system.cpu.load_1m: jvm.system.cpu.load_1m + # https://github.com/open-telemetry/semantic-conventions/pull/253 + process.runtime.jvm.buffer.usage: jvm.buffer.memory.usage + # https://github.com/open-telemetry/semantic-conventions/pull/253 + process.runtime.jvm.buffer.limit: jvm.buffer.memory.limit + process.runtime.jvm.buffer.count: jvm.buffer.count + # https://github.com/open-telemetry/semantic-conventions/pull/20 + - rename_attributes: + attribute_map: + type: jvm.memory.type + pool: jvm.memory.pool.name + apply_to_metrics: + - jvm.memory.usage + - jvm.memory.committed + - jvm.memory.limit + - jvm.memory.usage_after_last_gc + - jvm.memory.init + - rename_attributes: + attribute_map: + name: jvm.gc.name + action: jvm.gc.action + apply_to_metrics: + - jvm.gc.duration + - rename_attributes: + attribute_map: + daemon: thread.daemon + apply_to_metrics: + - jvm.threads.count + - rename_attributes: + attribute_map: + pool: jvm.buffer.pool.name + apply_to_metrics: + - jvm.buffer.usage + - jvm.buffer.limit + - jvm.buffer.count + # https://github.com/open-telemetry/semantic-conventions/pull/89 + - rename_attributes: + attribute_map: + state: system.cpu.state + cpu: system.cpu.logical_number + apply_to_metrics: + - system.cpu.time + - system.cpu.utilization + - rename_attributes: + attribute_map: + state: system.memory.state + apply_to_metrics: + - system.memory.usage + - system.memory.utilization + - rename_attributes: + attribute_map: + state: system.paging.state + apply_to_metrics: + - system.paging.usage + - system.paging.utilization + - rename_attributes: + attribute_map: + type: system.paging.type + direction: system.paging.direction + apply_to_metrics: + - system.paging.faults + - system.paging.operations + - rename_attributes: + attribute_map: + device: system.device + direction: system.disk.direction + apply_to_metrics: + - system.disk.io + - system.disk.operations + - system.disk.io_time + - system.disk.operation_time + - system.disk.merged + - rename_attributes: + attribute_map: + device: system.device + state: system.filesystem.state + type: system.filesystem.type + mode: system.filesystem.mode + mountpoint: system.filesystem.mountpoint + apply_to_metrics: + - system.filesystem.usage + - system.filesystem.utilization + - rename_attributes: + attribute_map: + device: system.device + direction: system.network.direction + protocol: network.protocol + state: system.network.state + apply_to_metrics: + - system.network.dropped + - system.network.packets + - system.network.errors + - system.network.io + - system.network.connections + - rename_attributes: + attribute_map: + status: system.processes.status + apply_to_metrics: + - system.processes.count + # https://github.com/open-telemetry/semantic-conventions/pull/247 + - rename_metrics: + http.server.request.size: http.server.request.body.size + http.server.response.size: http.server.response.body.size + resources: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/178 + - rename_attributes: + attribute_map: + telemetry.auto.version: telemetry.distro.version + 1.21.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3336 + - rename_attributes: + attribute_map: + messaging.kafka.client_id: messaging.client_id + messaging.rocketmq.client_id: messaging.client_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3402 + - rename_attributes: + attribute_map: + # net.peer.(name|port) attributes were usually populated on client side + # so they should be usually translated to server.(address|port) + # net.host.* attributes were only populated on server side + net.host.name: server.address + net.host.port: server.port + # was only populated on client side + net.sock.peer.name: server.socket.domain + # net.sock.peer.(addr|port) mapping is not possible + # since they applied to both client and server side + # were only populated on server side + net.sock.host.addr: server.socket.address + net.sock.host.port: server.socket.port + http.client_ip: client.address + # https://github.com/open-telemetry/opentelemetry-specification/pull/3426 + - rename_attributes: + attribute_map: + net.protocol.name: network.protocol.name + net.protocol.version: network.protocol.version + net.host.connection.type: network.connection.type + net.host.connection.subtype: network.connection.subtype + net.host.carrier.name: network.carrier.name + net.host.carrier.mcc: network.carrier.mcc + net.host.carrier.mnc: network.carrier.mnc + net.host.carrier.icc: network.carrier.icc + # https://github.com/open-telemetry/opentelemetry-specification/pull/3355 + - rename_attributes: + attribute_map: + http.method: http.request.method + http.status_code: http.response.status_code + http.scheme: url.scheme + http.url: url.full + http.request_content_length: http.request.body.size + http.response_content_length: http.response.body.size + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/53 + - rename_metrics: + process.runtime.jvm.cpu.utilization: process.runtime.jvm.cpu.recent_utilization + 1.20.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3272 + - rename_attributes: + attribute_map: + net.app.protocol.name: net.protocol.name + net.app.protocol.version: net.protocol.version + 1.19.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3209 + - rename_attributes: + attribute_map: + faas.execution: faas.invocation_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3188 + - rename_attributes: + attribute_map: + faas.id: cloud.resource_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3190 + - rename_attributes: + attribute_map: + http.user_agent: user_agent.original + resources: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3190 + - rename_attributes: + attribute_map: + browser.user_agent: user_agent.original + 1.18.0: + 1.17.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2957 + - rename_attributes: + attribute_map: + messaging.consumer_id: messaging.consumer.id + messaging.protocol: net.app.protocol.name + messaging.protocol_version: net.app.protocol.version + messaging.destination: messaging.destination.name + messaging.temp_destination: messaging.destination.temporary + messaging.destination_kind: messaging.destination.kind + messaging.message_id: messaging.message.id + messaging.conversation_id: messaging.message.conversation_id + messaging.message_payload_size_bytes: messaging.message.payload_size_bytes + messaging.message_payload_compressed_size_bytes: messaging.message.payload_compressed_size_bytes + messaging.rabbitmq.routing_key: messaging.rabbitmq.destination.routing_key + messaging.kafka.message_key: messaging.kafka.message.key + messaging.kafka.partition: messaging.kafka.destination.partition + messaging.kafka.tombstone: messaging.kafka.message.tombstone + messaging.rocketmq.message_type: messaging.rocketmq.message.type + messaging.rocketmq.message_tag: messaging.rocketmq.message.tag + messaging.rocketmq.message_keys: messaging.rocketmq.message.keys + messaging.kafka.consumer_group: messaging.kafka.consumer.group + 1.16.0: + 1.15.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2743 + - rename_attributes: + attribute_map: + http.retry_count: http.resend_count + 1.14.0: + 1.13.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2614 + - rename_attributes: + attribute_map: + net.peer.ip: net.sock.peer.addr + net.host.ip: net.sock.host.addr + 1.12.0: + 1.11.0: + 1.10.0: + 1.9.0: + 1.8.0: + spans: + changes: + - rename_attributes: + attribute_map: + db.cassandra.keyspace: db.name + db.hbase.namespace: db.name + 1.7.0: + 1.6.1: + 1.5.0: + 1.4.0: diff --git a/schemas/1.23.1 b/schemas/1.23.1 new file mode 100644 index 0000000000..3662ca07b5 --- /dev/null +++ b/schemas/1.23.1 @@ -0,0 +1,294 @@ +file_format: 1.1.0 +schema_url: https://opentelemetry.io/schemas/1.23.1 +versions: + 1.23.1: + 1.23.0: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/20 + - rename_attributes: + attribute_map: + thread.daemon: jvm.thread.daemon + apply_to_metrics: + - jvm.thread.count + 1.22.0: + spans: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/229 + - rename_attributes: + attribute_map: + messaging.message.payload_size_bytes: messaging.message.body.size + # https://github.com/open-telemetry/opentelemetry-specification/pull/374 + - rename_attributes: + attribute_map: + http.resend_count: http.request.resend_count + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/224 + - rename_metrics: + http.client.duration: http.client.request.duration + http.server.duration: http.server.request.duration + # https://github.com/open-telemetry/semantic-conventions/pull/241 + - rename_metrics: + process.runtime.jvm.memory.usage: jvm.memory.usage + process.runtime.jvm.memory.committed: jvm.memory.committed + process.runtime.jvm.memory.limit: jvm.memory.limit + process.runtime.jvm.memory.usage_after_last_gc: jvm.memory.usage_after_last_gc + process.runtime.jvm.gc.duration: jvm.gc.duration + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.threads.count: jvm.thread.count + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.classes.loaded: jvm.class.loaded + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.classes.unloaded: jvm.class.unloaded + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + # and https://github.com/open-telemetry/semantic-conventions/pull/60 + process.runtime.jvm.classes.current_loaded: jvm.class.count + process.runtime.jvm.cpu.time: jvm.cpu.time + process.runtime.jvm.cpu.recent_utilization: jvm.cpu.recent_utilization + process.runtime.jvm.memory.init: jvm.memory.init + process.runtime.jvm.system.cpu.utilization: jvm.system.cpu.utilization + process.runtime.jvm.system.cpu.load_1m: jvm.system.cpu.load_1m + # https://github.com/open-telemetry/semantic-conventions/pull/253 + process.runtime.jvm.buffer.usage: jvm.buffer.memory.usage + # https://github.com/open-telemetry/semantic-conventions/pull/253 + process.runtime.jvm.buffer.limit: jvm.buffer.memory.limit + process.runtime.jvm.buffer.count: jvm.buffer.count + # https://github.com/open-telemetry/semantic-conventions/pull/20 + - rename_attributes: + attribute_map: + type: jvm.memory.type + pool: jvm.memory.pool.name + apply_to_metrics: + - jvm.memory.usage + - jvm.memory.committed + - jvm.memory.limit + - jvm.memory.usage_after_last_gc + - jvm.memory.init + - rename_attributes: + attribute_map: + name: jvm.gc.name + action: jvm.gc.action + apply_to_metrics: + - jvm.gc.duration + - rename_attributes: + attribute_map: + daemon: thread.daemon + apply_to_metrics: + - jvm.threads.count + - rename_attributes: + attribute_map: + pool: jvm.buffer.pool.name + apply_to_metrics: + - jvm.buffer.usage + - jvm.buffer.limit + - jvm.buffer.count + # https://github.com/open-telemetry/semantic-conventions/pull/89 + - rename_attributes: + attribute_map: + state: system.cpu.state + cpu: system.cpu.logical_number + apply_to_metrics: + - system.cpu.time + - system.cpu.utilization + - rename_attributes: + attribute_map: + state: system.memory.state + apply_to_metrics: + - system.memory.usage + - system.memory.utilization + - rename_attributes: + attribute_map: + state: system.paging.state + apply_to_metrics: + - system.paging.usage + - system.paging.utilization + - rename_attributes: + attribute_map: + type: system.paging.type + direction: system.paging.direction + apply_to_metrics: + - system.paging.faults + - system.paging.operations + - rename_attributes: + attribute_map: + device: system.device + direction: system.disk.direction + apply_to_metrics: + - system.disk.io + - system.disk.operations + - system.disk.io_time + - system.disk.operation_time + - system.disk.merged + - rename_attributes: + attribute_map: + device: system.device + state: system.filesystem.state + type: system.filesystem.type + mode: system.filesystem.mode + mountpoint: system.filesystem.mountpoint + apply_to_metrics: + - system.filesystem.usage + - system.filesystem.utilization + - rename_attributes: + attribute_map: + device: system.device + direction: system.network.direction + protocol: network.protocol + state: system.network.state + apply_to_metrics: + - system.network.dropped + - system.network.packets + - system.network.errors + - system.network.io + - system.network.connections + - rename_attributes: + attribute_map: + status: system.processes.status + apply_to_metrics: + - system.processes.count + # https://github.com/open-telemetry/semantic-conventions/pull/247 + - rename_metrics: + http.server.request.size: http.server.request.body.size + http.server.response.size: http.server.response.body.size + resources: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/178 + - rename_attributes: + attribute_map: + telemetry.auto.version: telemetry.distro.version + 1.21.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3336 + - rename_attributes: + attribute_map: + messaging.kafka.client_id: messaging.client_id + messaging.rocketmq.client_id: messaging.client_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3402 + - rename_attributes: + attribute_map: + # net.peer.(name|port) attributes were usually populated on client side + # so they should be usually translated to server.(address|port) + # net.host.* attributes were only populated on server side + net.host.name: server.address + net.host.port: server.port + # was only populated on client side + net.sock.peer.name: server.socket.domain + # net.sock.peer.(addr|port) mapping is not possible + # since they applied to both client and server side + # were only populated on server side + net.sock.host.addr: server.socket.address + net.sock.host.port: server.socket.port + http.client_ip: client.address + # https://github.com/open-telemetry/opentelemetry-specification/pull/3426 + - rename_attributes: + attribute_map: + net.protocol.name: network.protocol.name + net.protocol.version: network.protocol.version + net.host.connection.type: network.connection.type + net.host.connection.subtype: network.connection.subtype + net.host.carrier.name: network.carrier.name + net.host.carrier.mcc: network.carrier.mcc + net.host.carrier.mnc: network.carrier.mnc + net.host.carrier.icc: network.carrier.icc + # https://github.com/open-telemetry/opentelemetry-specification/pull/3355 + - rename_attributes: + attribute_map: + http.method: http.request.method + http.status_code: http.response.status_code + http.scheme: url.scheme + http.url: url.full + http.request_content_length: http.request.body.size + http.response_content_length: http.response.body.size + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/53 + - rename_metrics: + process.runtime.jvm.cpu.utilization: process.runtime.jvm.cpu.recent_utilization + 1.20.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3272 + - rename_attributes: + attribute_map: + net.app.protocol.name: net.protocol.name + net.app.protocol.version: net.protocol.version + 1.19.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3209 + - rename_attributes: + attribute_map: + faas.execution: faas.invocation_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3188 + - rename_attributes: + attribute_map: + faas.id: cloud.resource_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3190 + - rename_attributes: + attribute_map: + http.user_agent: user_agent.original + resources: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3190 + - rename_attributes: + attribute_map: + browser.user_agent: user_agent.original + 1.18.0: + 1.17.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2957 + - rename_attributes: + attribute_map: + messaging.consumer_id: messaging.consumer.id + messaging.protocol: net.app.protocol.name + messaging.protocol_version: net.app.protocol.version + messaging.destination: messaging.destination.name + messaging.temp_destination: messaging.destination.temporary + messaging.destination_kind: messaging.destination.kind + messaging.message_id: messaging.message.id + messaging.conversation_id: messaging.message.conversation_id + messaging.message_payload_size_bytes: messaging.message.payload_size_bytes + messaging.message_payload_compressed_size_bytes: messaging.message.payload_compressed_size_bytes + messaging.rabbitmq.routing_key: messaging.rabbitmq.destination.routing_key + messaging.kafka.message_key: messaging.kafka.message.key + messaging.kafka.partition: messaging.kafka.destination.partition + messaging.kafka.tombstone: messaging.kafka.message.tombstone + messaging.rocketmq.message_type: messaging.rocketmq.message.type + messaging.rocketmq.message_tag: messaging.rocketmq.message.tag + messaging.rocketmq.message_keys: messaging.rocketmq.message.keys + messaging.kafka.consumer_group: messaging.kafka.consumer.group + 1.16.0: + 1.15.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2743 + - rename_attributes: + attribute_map: + http.retry_count: http.resend_count + 1.14.0: + 1.13.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2614 + - rename_attributes: + attribute_map: + net.peer.ip: net.sock.peer.addr + net.host.ip: net.sock.host.addr + 1.12.0: + 1.11.0: + 1.10.0: + 1.9.0: + 1.8.0: + spans: + changes: + - rename_attributes: + attribute_map: + db.cassandra.keyspace: db.name + db.hbase.namespace: db.name + 1.7.0: + 1.6.1: + 1.5.0: + 1.4.0: diff --git a/schemas/1.24.0 b/schemas/1.24.0 new file mode 100644 index 0000000000..f1de094f68 --- /dev/null +++ b/schemas/1.24.0 @@ -0,0 +1,306 @@ +file_format: 1.1.0 +schema_url: https://opentelemetry.io/schemas/1.24.0 +versions: + 1.24.0: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/536 + - rename_metrics: + jvm.memory.usage: jvm.memory.used + jvm.memory.usage_after_last_gc: jvm.memory.used_after_last_gc + # https://github.com/open-telemetry/semantic-conventions/pull/530 + - rename_attributes: + attribute_map: + system.network.io.direction: network.io.direction + system.disk.io.direction: disk.io.direction + 1.23.1: + 1.23.0: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/20 + - rename_attributes: + attribute_map: + thread.daemon: jvm.thread.daemon + apply_to_metrics: + - jvm.thread.count + 1.22.0: + spans: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/229 + - rename_attributes: + attribute_map: + messaging.message.payload_size_bytes: messaging.message.body.size + # https://github.com/open-telemetry/opentelemetry-specification/pull/374 + - rename_attributes: + attribute_map: + http.resend_count: http.request.resend_count + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/224 + - rename_metrics: + http.client.duration: http.client.request.duration + http.server.duration: http.server.request.duration + # https://github.com/open-telemetry/semantic-conventions/pull/241 + - rename_metrics: + process.runtime.jvm.memory.usage: jvm.memory.usage + process.runtime.jvm.memory.committed: jvm.memory.committed + process.runtime.jvm.memory.limit: jvm.memory.limit + process.runtime.jvm.memory.usage_after_last_gc: jvm.memory.usage_after_last_gc + process.runtime.jvm.gc.duration: jvm.gc.duration + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.threads.count: jvm.thread.count + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.classes.loaded: jvm.class.loaded + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.classes.unloaded: jvm.class.unloaded + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + # and https://github.com/open-telemetry/semantic-conventions/pull/60 + process.runtime.jvm.classes.current_loaded: jvm.class.count + process.runtime.jvm.cpu.time: jvm.cpu.time + process.runtime.jvm.cpu.recent_utilization: jvm.cpu.recent_utilization + process.runtime.jvm.memory.init: jvm.memory.init + process.runtime.jvm.system.cpu.utilization: jvm.system.cpu.utilization + process.runtime.jvm.system.cpu.load_1m: jvm.system.cpu.load_1m + # https://github.com/open-telemetry/semantic-conventions/pull/253 + process.runtime.jvm.buffer.usage: jvm.buffer.memory.usage + # https://github.com/open-telemetry/semantic-conventions/pull/253 + process.runtime.jvm.buffer.limit: jvm.buffer.memory.limit + process.runtime.jvm.buffer.count: jvm.buffer.count + # https://github.com/open-telemetry/semantic-conventions/pull/20 + - rename_attributes: + attribute_map: + type: jvm.memory.type + pool: jvm.memory.pool.name + apply_to_metrics: + - jvm.memory.usage + - jvm.memory.committed + - jvm.memory.limit + - jvm.memory.usage_after_last_gc + - jvm.memory.init + - rename_attributes: + attribute_map: + name: jvm.gc.name + action: jvm.gc.action + apply_to_metrics: + - jvm.gc.duration + - rename_attributes: + attribute_map: + daemon: thread.daemon + apply_to_metrics: + - jvm.threads.count + - rename_attributes: + attribute_map: + pool: jvm.buffer.pool.name + apply_to_metrics: + - jvm.buffer.usage + - jvm.buffer.limit + - jvm.buffer.count + # https://github.com/open-telemetry/semantic-conventions/pull/89 + - rename_attributes: + attribute_map: + state: system.cpu.state + cpu: system.cpu.logical_number + apply_to_metrics: + - system.cpu.time + - system.cpu.utilization + - rename_attributes: + attribute_map: + state: system.memory.state + apply_to_metrics: + - system.memory.usage + - system.memory.utilization + - rename_attributes: + attribute_map: + state: system.paging.state + apply_to_metrics: + - system.paging.usage + - system.paging.utilization + - rename_attributes: + attribute_map: + type: system.paging.type + direction: system.paging.direction + apply_to_metrics: + - system.paging.faults + - system.paging.operations + - rename_attributes: + attribute_map: + device: system.device + direction: system.disk.direction + apply_to_metrics: + - system.disk.io + - system.disk.operations + - system.disk.io_time + - system.disk.operation_time + - system.disk.merged + - rename_attributes: + attribute_map: + device: system.device + state: system.filesystem.state + type: system.filesystem.type + mode: system.filesystem.mode + mountpoint: system.filesystem.mountpoint + apply_to_metrics: + - system.filesystem.usage + - system.filesystem.utilization + - rename_attributes: + attribute_map: + device: system.device + direction: system.network.direction + protocol: network.protocol + state: system.network.state + apply_to_metrics: + - system.network.dropped + - system.network.packets + - system.network.errors + - system.network.io + - system.network.connections + - rename_attributes: + attribute_map: + status: system.processes.status + apply_to_metrics: + - system.processes.count + # https://github.com/open-telemetry/semantic-conventions/pull/247 + - rename_metrics: + http.server.request.size: http.server.request.body.size + http.server.response.size: http.server.response.body.size + resources: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/178 + - rename_attributes: + attribute_map: + telemetry.auto.version: telemetry.distro.version + 1.21.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3336 + - rename_attributes: + attribute_map: + messaging.kafka.client_id: messaging.client_id + messaging.rocketmq.client_id: messaging.client_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3402 + - rename_attributes: + attribute_map: + # net.peer.(name|port) attributes were usually populated on client side + # so they should be usually translated to server.(address|port) + # net.host.* attributes were only populated on server side + net.host.name: server.address + net.host.port: server.port + # was only populated on client side + net.sock.peer.name: server.socket.domain + # net.sock.peer.(addr|port) mapping is not possible + # since they applied to both client and server side + # were only populated on server side + net.sock.host.addr: server.socket.address + net.sock.host.port: server.socket.port + http.client_ip: client.address + # https://github.com/open-telemetry/opentelemetry-specification/pull/3426 + - rename_attributes: + attribute_map: + net.protocol.name: network.protocol.name + net.protocol.version: network.protocol.version + net.host.connection.type: network.connection.type + net.host.connection.subtype: network.connection.subtype + net.host.carrier.name: network.carrier.name + net.host.carrier.mcc: network.carrier.mcc + net.host.carrier.mnc: network.carrier.mnc + net.host.carrier.icc: network.carrier.icc + # https://github.com/open-telemetry/opentelemetry-specification/pull/3355 + - rename_attributes: + attribute_map: + http.method: http.request.method + http.status_code: http.response.status_code + http.scheme: url.scheme + http.url: url.full + http.request_content_length: http.request.body.size + http.response_content_length: http.response.body.size + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/53 + - rename_metrics: + process.runtime.jvm.cpu.utilization: process.runtime.jvm.cpu.recent_utilization + 1.20.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3272 + - rename_attributes: + attribute_map: + net.app.protocol.name: net.protocol.name + net.app.protocol.version: net.protocol.version + 1.19.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3209 + - rename_attributes: + attribute_map: + faas.execution: faas.invocation_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3188 + - rename_attributes: + attribute_map: + faas.id: cloud.resource_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3190 + - rename_attributes: + attribute_map: + http.user_agent: user_agent.original + resources: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3190 + - rename_attributes: + attribute_map: + browser.user_agent: user_agent.original + 1.18.0: + 1.17.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2957 + - rename_attributes: + attribute_map: + messaging.consumer_id: messaging.consumer.id + messaging.protocol: net.app.protocol.name + messaging.protocol_version: net.app.protocol.version + messaging.destination: messaging.destination.name + messaging.temp_destination: messaging.destination.temporary + messaging.destination_kind: messaging.destination.kind + messaging.message_id: messaging.message.id + messaging.conversation_id: messaging.message.conversation_id + messaging.message_payload_size_bytes: messaging.message.payload_size_bytes + messaging.message_payload_compressed_size_bytes: messaging.message.payload_compressed_size_bytes + messaging.rabbitmq.routing_key: messaging.rabbitmq.destination.routing_key + messaging.kafka.message_key: messaging.kafka.message.key + messaging.kafka.partition: messaging.kafka.destination.partition + messaging.kafka.tombstone: messaging.kafka.message.tombstone + messaging.rocketmq.message_type: messaging.rocketmq.message.type + messaging.rocketmq.message_tag: messaging.rocketmq.message.tag + messaging.rocketmq.message_keys: messaging.rocketmq.message.keys + messaging.kafka.consumer_group: messaging.kafka.consumer.group + 1.16.0: + 1.15.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2743 + - rename_attributes: + attribute_map: + http.retry_count: http.resend_count + 1.14.0: + 1.13.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2614 + - rename_attributes: + attribute_map: + net.peer.ip: net.sock.peer.addr + net.host.ip: net.sock.host.addr + 1.12.0: + 1.11.0: + 1.10.0: + 1.9.0: + 1.8.0: + spans: + changes: + - rename_attributes: + attribute_map: + db.cassandra.keyspace: db.name + db.hbase.namespace: db.name + 1.7.0: + 1.6.1: + 1.5.0: + 1.4.0: diff --git a/schemas/1.25.0 b/schemas/1.25.0 new file mode 100644 index 0000000000..774c245622 --- /dev/null +++ b/schemas/1.25.0 @@ -0,0 +1,360 @@ +file_format: 1.1.0 +schema_url: https://opentelemetry.io/schemas/1.25.0 +versions: + 1.25.0: + spans: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/798 + - rename_attributes: + attribute_map: + messaging.kafka.destination.partition: messaging.destination.partition.id + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/484 + - rename_attributes: + attribute_map: + system.processes.status: system.process.status + apply_to_metrics: + - system.processes.count + - rename_metrics: + system.processes.count: system.process.count + system.processes.created: system.process.created + # https://github.com/open-telemetry/semantic-conventions/pull/625 + - rename_attributes: + attribute_map: + container.labels: container.label + k8s.pod.labels: k8s.pod.label + # https://github.com/open-telemetry/semantic-conventions/pull/330 + - rename_metrics: + process.threads: process.thread.count + process.open_file_descriptors: process.open_file_descriptor.count + - rename_attributes: + attribute_map: + state: process.cpu.state + apply_to_metrics: + - process.cpu.time + - process.cpu.utilization + - rename_attributes: + attribute_map: + direction: disk.io.direction + apply_to_metrics: + - process.disk.io + - rename_attributes: + attribute_map: + type: process.context_switch_type + apply_to_metrics: + - process.context_switches + - rename_attributes: + attribute_map: + direction: network.io.direction + apply_to_metrics: + - process.network.io + - rename_attributes: + attribute_map: + type: process.paging.fault_type + apply_to_metrics: + - process.paging.faults + + 1.24.0: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/536 + - rename_metrics: + jvm.memory.usage: jvm.memory.used + jvm.memory.usage_after_last_gc: jvm.memory.used_after_last_gc + # https://github.com/open-telemetry/semantic-conventions/pull/530 + - rename_attributes: + attribute_map: + system.network.io.direction: network.io.direction + system.disk.io.direction: disk.io.direction + 1.23.1: + 1.23.0: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/20 + - rename_attributes: + attribute_map: + thread.daemon: jvm.thread.daemon + apply_to_metrics: + - jvm.thread.count + 1.22.0: + spans: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/229 + - rename_attributes: + attribute_map: + messaging.message.payload_size_bytes: messaging.message.body.size + # https://github.com/open-telemetry/opentelemetry-specification/pull/374 + - rename_attributes: + attribute_map: + http.resend_count: http.request.resend_count + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/224 + - rename_metrics: + http.client.duration: http.client.request.duration + http.server.duration: http.server.request.duration + # https://github.com/open-telemetry/semantic-conventions/pull/241 + - rename_metrics: + process.runtime.jvm.memory.usage: jvm.memory.usage + process.runtime.jvm.memory.committed: jvm.memory.committed + process.runtime.jvm.memory.limit: jvm.memory.limit + process.runtime.jvm.memory.usage_after_last_gc: jvm.memory.usage_after_last_gc + process.runtime.jvm.gc.duration: jvm.gc.duration + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.threads.count: jvm.thread.count + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.classes.loaded: jvm.class.loaded + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.classes.unloaded: jvm.class.unloaded + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + # and https://github.com/open-telemetry/semantic-conventions/pull/60 + process.runtime.jvm.classes.current_loaded: jvm.class.count + process.runtime.jvm.cpu.time: jvm.cpu.time + process.runtime.jvm.cpu.recent_utilization: jvm.cpu.recent_utilization + process.runtime.jvm.memory.init: jvm.memory.init + process.runtime.jvm.system.cpu.utilization: jvm.system.cpu.utilization + process.runtime.jvm.system.cpu.load_1m: jvm.system.cpu.load_1m + # https://github.com/open-telemetry/semantic-conventions/pull/253 + process.runtime.jvm.buffer.usage: jvm.buffer.memory.usage + # https://github.com/open-telemetry/semantic-conventions/pull/253 + process.runtime.jvm.buffer.limit: jvm.buffer.memory.limit + process.runtime.jvm.buffer.count: jvm.buffer.count + # https://github.com/open-telemetry/semantic-conventions/pull/20 + - rename_attributes: + attribute_map: + type: jvm.memory.type + pool: jvm.memory.pool.name + apply_to_metrics: + - jvm.memory.usage + - jvm.memory.committed + - jvm.memory.limit + - jvm.memory.usage_after_last_gc + - jvm.memory.init + - rename_attributes: + attribute_map: + name: jvm.gc.name + action: jvm.gc.action + apply_to_metrics: + - jvm.gc.duration + - rename_attributes: + attribute_map: + daemon: thread.daemon + apply_to_metrics: + - jvm.threads.count + - rename_attributes: + attribute_map: + pool: jvm.buffer.pool.name + apply_to_metrics: + - jvm.buffer.memory.usage + - jvm.buffer.memory.limit + - jvm.buffer.count + # https://github.com/open-telemetry/semantic-conventions/pull/89 + - rename_attributes: + attribute_map: + state: system.cpu.state + cpu: system.cpu.logical_number + apply_to_metrics: + - system.cpu.time + - system.cpu.utilization + - rename_attributes: + attribute_map: + state: system.memory.state + apply_to_metrics: + - system.memory.usage + - system.memory.utilization + - rename_attributes: + attribute_map: + state: system.paging.state + apply_to_metrics: + - system.paging.usage + - system.paging.utilization + - rename_attributes: + attribute_map: + type: system.paging.type + direction: system.paging.direction + apply_to_metrics: + - system.paging.faults + - system.paging.operations + - rename_attributes: + attribute_map: + device: system.device + direction: system.disk.direction + apply_to_metrics: + - system.disk.io + - system.disk.operations + - system.disk.io_time + - system.disk.operation_time + - system.disk.merged + - rename_attributes: + attribute_map: + device: system.device + state: system.filesystem.state + type: system.filesystem.type + mode: system.filesystem.mode + mountpoint: system.filesystem.mountpoint + apply_to_metrics: + - system.filesystem.usage + - system.filesystem.utilization + - rename_attributes: + attribute_map: + device: system.device + direction: system.network.direction + protocol: network.protocol + state: system.network.state + apply_to_metrics: + - system.network.dropped + - system.network.packets + - system.network.errors + - system.network.io + - system.network.connections + - rename_attributes: + attribute_map: + status: system.processes.status + apply_to_metrics: + - system.processes.count + # https://github.com/open-telemetry/semantic-conventions/pull/247 + - rename_metrics: + http.server.request.size: http.server.request.body.size + http.server.response.size: http.server.response.body.size + resources: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/178 + - rename_attributes: + attribute_map: + telemetry.auto.version: telemetry.distro.version + 1.21.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3336 + - rename_attributes: + attribute_map: + messaging.kafka.client_id: messaging.client_id + messaging.rocketmq.client_id: messaging.client_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3402 + - rename_attributes: + attribute_map: + # net.peer.(name|port) attributes were usually populated on client side + # so they should be usually translated to server.(address|port) + # net.host.* attributes were only populated on server side + net.host.name: server.address + net.host.port: server.port + # was only populated on client side + net.sock.peer.name: server.socket.domain + # net.sock.peer.(addr|port) mapping is not possible + # since they applied to both client and server side + # were only populated on server side + net.sock.host.addr: server.socket.address + net.sock.host.port: server.socket.port + http.client_ip: client.address + # https://github.com/open-telemetry/opentelemetry-specification/pull/3426 + - rename_attributes: + attribute_map: + net.protocol.name: network.protocol.name + net.protocol.version: network.protocol.version + net.host.connection.type: network.connection.type + net.host.connection.subtype: network.connection.subtype + net.host.carrier.name: network.carrier.name + net.host.carrier.mcc: network.carrier.mcc + net.host.carrier.mnc: network.carrier.mnc + net.host.carrier.icc: network.carrier.icc + # https://github.com/open-telemetry/opentelemetry-specification/pull/3355 + - rename_attributes: + attribute_map: + http.method: http.request.method + http.status_code: http.response.status_code + http.scheme: url.scheme + http.url: url.full + http.request_content_length: http.request.body.size + http.response_content_length: http.response.body.size + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/53 + - rename_metrics: + process.runtime.jvm.cpu.utilization: process.runtime.jvm.cpu.recent_utilization + 1.20.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3272 + - rename_attributes: + attribute_map: + net.app.protocol.name: net.protocol.name + net.app.protocol.version: net.protocol.version + 1.19.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3209 + - rename_attributes: + attribute_map: + faas.execution: faas.invocation_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3188 + - rename_attributes: + attribute_map: + faas.id: cloud.resource_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3190 + - rename_attributes: + attribute_map: + http.user_agent: user_agent.original + resources: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3190 + - rename_attributes: + attribute_map: + browser.user_agent: user_agent.original + 1.18.0: + 1.17.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2957 + - rename_attributes: + attribute_map: + messaging.consumer_id: messaging.consumer.id + messaging.protocol: net.app.protocol.name + messaging.protocol_version: net.app.protocol.version + messaging.destination: messaging.destination.name + messaging.temp_destination: messaging.destination.temporary + messaging.destination_kind: messaging.destination.kind + messaging.message_id: messaging.message.id + messaging.conversation_id: messaging.message.conversation_id + messaging.message_payload_size_bytes: messaging.message.payload_size_bytes + messaging.message_payload_compressed_size_bytes: messaging.message.payload_compressed_size_bytes + messaging.rabbitmq.routing_key: messaging.rabbitmq.destination.routing_key + messaging.kafka.message_key: messaging.kafka.message.key + messaging.kafka.partition: messaging.kafka.destination.partition + messaging.kafka.tombstone: messaging.kafka.message.tombstone + messaging.rocketmq.message_type: messaging.rocketmq.message.type + messaging.rocketmq.message_tag: messaging.rocketmq.message.tag + messaging.rocketmq.message_keys: messaging.rocketmq.message.keys + messaging.kafka.consumer_group: messaging.kafka.consumer.group + 1.16.0: + 1.15.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2743 + - rename_attributes: + attribute_map: + http.retry_count: http.resend_count + 1.14.0: + 1.13.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2614 + - rename_attributes: + attribute_map: + net.peer.ip: net.sock.peer.addr + net.host.ip: net.sock.host.addr + 1.12.0: + 1.11.0: + 1.10.0: + 1.9.0: + 1.8.0: + spans: + changes: + - rename_attributes: + attribute_map: + db.cassandra.keyspace: db.name + db.hbase.namespace: db.name + 1.7.0: + 1.6.1: + 1.5.0: + 1.4.0: diff --git a/templates/registry/markdown/attribute_name.j2 b/templates/registry/markdown/attribute_name.j2 new file mode 100644 index 0000000000..e268e6f93d --- /dev/null +++ b/templates/registry/markdown/attribute_name.j2 @@ -0,0 +1,2 @@ +{%- if attribute.type is startingwith("template[") %}`{{ attribute.name }}.` +{%- else %}`{{ attribute.name }}`{%- endif %} \ No newline at end of file diff --git a/templates/registry/markdown/attribute_namespace.md.j2 b/templates/registry/markdown/attribute_namespace.md.j2 new file mode 100644 index 0000000000..e41f6bd09d --- /dev/null +++ b/templates/registry/markdown/attribute_namespace.md.j2 @@ -0,0 +1,45 @@ +{#- This template is rendered per top-level registry namespace. -#} +{#- It consists of two variables: -#} +{#- - id: The top-level namespace id. -#} +{#- - groups: A sequence of all attribute groups under this namespace. -#} +{#- This includes deprecated groups. -#} +{% import 'stability.j2' as stability %} +{% import 'notes.j2' as notes %} +{%- set my_file_name = ctx.id | lower | kebab_case ~ ".md" -%} +{{- template.set_file_name(my_file_name) -}} + + + + + + +# {{ ctx.id | title_case | acronym }} + +{% if ctx.groups | length > 1 %}{% for group in ctx.groups | sort(attribute="id") %} +{%- set group_name = group.id | split_id | list | reject("eq", "registry") | join(" ") -%} +- [{{ group_name | title_case }}](#{{group_name | kebab_case }}-attributes) +{% endfor %}{% endif %} +{% for group in ctx.groups | sort(attribute="id") %} +## {{ group.id | split_id | list | reject("eq", "registry") | join(" ") | title_case }} Attributes + +{{ group.brief }} + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +{%- for attribute in group.attributes | sort(attribute="name") %} +| {% include "attribute_name.j2" %} | {% include "attribute_type.j2" | trim %} | {{ attribute.brief | trim }}{{ notes.add(attribute.note) }} | {% include "examples.j2" | trim %} | {{ stability.badge(attribute.stability, attribute.deprecated) | trim }} | +{%- endfor %} + +{{ notes.render() }} +{% for enum in group.attributes | sort(attribute="name") %} +{%- if enum.type is mapping -%}{#- We should use a filter for enums vs. this if. -#} +`{{enum.name}}` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +{% for espec in enum.type.members %}| `{{espec.value}}` | {{espec.brief | trim}} | {{ stability.badge(espec.stability, espec.deprecated) }} | +{% endfor %} +{% endif %} +{%- endfor -%} +{%- endfor -%} diff --git a/templates/registry/markdown/attribute_type.j2 b/templates/registry/markdown/attribute_type.j2 new file mode 100644 index 0000000000..dd4905253d --- /dev/null +++ b/templates/registry/markdown/attribute_type.j2 @@ -0,0 +1,13 @@ +{%- if attribute.type is mapping %} +{%- if attribute.type.members[0].value is string %}string{%- endif %} +{%- if attribute.type.members[0].value is int %}int{%- endif %} +{%- if attribute.type.members[0].value is float %}double{%- endif %} +{%- elif attribute.type == "template[boolean]" %}boolean +{%- elif attribute.type == "template[int]" %}int +{%- elif attribute.type == "template[double]" %}double +{%- elif attribute.type == "template[string]" %}string +{%- elif attribute.type == "template[boolean[]]" %}boolean[] +{%- elif attribute.type == "template[int[]]" %}int[] +{%- elif attribute.type == "template[double[]]" %}double[] +{%- elif attribute.type == "template[string[]]" %}string[] +{%- else %}{{ attribute.type | trim }}{%- endif %} \ No newline at end of file diff --git a/templates/registry/markdown/examples.j2 b/templates/registry/markdown/examples.j2 new file mode 100644 index 0000000000..63cfcae389 --- /dev/null +++ b/templates/registry/markdown/examples.j2 @@ -0,0 +1,10 @@ +{%- if attribute.type is mapping %} +{%- for e in attribute.type.members %}{% if loop.index0 < 3 %}{% if loop.first == false %}; {% endif %}`{{ e.value | trim }}`{% endif %}{%- endfor %} +{%- else %} +{%- if attribute.examples %} +{%- if attribute.examples is sequence %} +{%- for example in attribute.examples %}{%if loop.first == false %}; {% endif %}`{{ example }}`{%- endfor %} +{%- else %}`{{ attribute.examples | trim }}` +{%- endif %} +{%- endif %} +{%- endif %} diff --git a/templates/registry/markdown/notes.j2 b/templates/registry/markdown/notes.j2 new file mode 100644 index 0000000000..c1d382ab8b --- /dev/null +++ b/templates/registry/markdown/notes.j2 @@ -0,0 +1,16 @@ +{%- set ns = namespace(notes=[],index=0) -%} +{%- macro add(note) %}{% if note %}{% set ns.notes = [ns.notes, [note]] | flatten %} [{{ ns.notes | length + ns.index }}]{% endif %}{% endmacro %} +{%- macro add_with_limit(note) %} +{%- if note | length > 50 %} +{%- set ns.notes = [ns.notes, [note]] | flatten -%} +[{{ ns.notes | length + ns.index }}] +{%- elif note -%} +{{ note }} +{%- endif %} +{%- endmacro %} +{%- macro render() %} +{% for note in ns.notes %}**[{{ns.index+loop.index}}]:** {{note}} +{% endfor %} +{%- set ns.index = ns.notes | length + ns.index -%} +{%- set ns.notes = [] -%} +{%- endmacro %} \ No newline at end of file diff --git a/templates/registry/markdown/readme.md.j2 b/templates/registry/markdown/readme.md.j2 new file mode 100644 index 0000000000..14cf1f38d0 --- /dev/null +++ b/templates/registry/markdown/readme.md.j2 @@ -0,0 +1,40 @@ +{{- template.set_file_name("README.md") -}} + + + + + +# Attribute Registry + +The attributes registry is the place where attributes are defined. An attribute definition covers the following properties of an attribute: + +- the `id` (the fully qualified name) of the attribute +- the `type` of the attribute +- the `stability` of the attribute +- a `brief` description of the attribute and optionally a longer `note` +- example values + +Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id` and `type` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context. + +A definition of an attribute in the registry doesn't necessarily imply that the attribute is used in any of the semantic conventions. + +If applicable, application developers are encouraged to use existing attributes from this registry. See also [these recommendations][developers recommendations] regarding attribute selection and attribute naming for custom use cases. + +All registered attributes are listed by namespace in this registry. + +> **Warning** +> The following registry overview is a work in progress. +> +> Further attribute namespaces are currently being migrated and will appear in this registry soon. + +Currently, the following namespaces exist: + +{% for bundle in ctx %} +{%- set my_file_name = bundle.id | kebab_case ~ ".md" -%} +- [{{ bundle.id | title_case | acronym }}]({{ my_file_name }}) +{% endfor %} + +[developers recommendations]: ../general/attribute-naming.md#recommendations-for-application-developers \ No newline at end of file diff --git a/templates/registry/markdown/stability.j2 b/templates/registry/markdown/stability.j2 new file mode 100644 index 0000000000..7f43919196 --- /dev/null +++ b/templates/registry/markdown/stability.j2 @@ -0,0 +1,7 @@ +{% macro badge(stability, deprecated) -%} +{%- if deprecated %} ![Deprecated](https://img.shields.io/badge/-deprecated-red)
{{ deprecated | trim }} +{%- elif stability == "stable" %}![Stable](https://img.shields.io/badge/-stable-lightgreen) +{%- elif stability == "deprecated" %}![Deprecated](https://img.shields.io/badge/-deprecated-red) +{%- else %}![Experimental](https://img.shields.io/badge/-experimental-blue) +{%- endif %} +{%- endmacro %} \ No newline at end of file diff --git a/templates/registry/markdown/weaver.yaml b/templates/registry/markdown/weaver.yaml new file mode 100644 index 0000000000..19cbd089a6 --- /dev/null +++ b/templates/registry/markdown/weaver.yaml @@ -0,0 +1,32 @@ +templates: + - pattern: readme.md.j2 + filter: '.groups | map(select(.type == "attribute_group")) | map(select(.id | startswith("registry"))) | group_by(.id | split(".") | .[1]) | map({id: .[0].id | split(".") | .[1], groups: .})' + application_mode: single + - pattern: attribute_namespace.md.j2 + filter: '.groups | map(select(.type == "attribute_group")) | map(select(.id | startswith("registry"))) | group_by(.id | split(".") | .[1]) | map({id: .[0].id | split(".") | .[1], groups: .})' + application_mode: each +acronyms: + - AI + - iOS + - AWS + - CloudEvents + - CosmosDB + - DynamoDB + - ECS + - EKS + - GraphQL + - GCP + - GCE + - HTTP + - JVM + - OCI + - OTel + - OpenTracing + - OS + - RabbitMQ + - RocketMQ + - RPC + - S3 + - SignalR + - TLS + - URL