diff --git a/.chloggen/1156.yaml b/.chloggen/1156.yaml new file mode 100644 index 0000000000..56ef916b8e --- /dev/null +++ b/.chloggen/1156.yaml @@ -0,0 +1,7 @@ +change_type: breaking + +component: messaging + +note: Rename `messaging.kafka.message.offset` to `messaging.kafka.offset` + +issues: [1156] diff --git a/.chloggen/1166.yaml b/.chloggen/1166.yaml new file mode 100644 index 0000000000..2202ecc8d1 --- /dev/null +++ b/.chloggen/1166.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: Sampling relevant attributes defined for database client spans + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [ 1019 ] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/.chloggen/1167.yaml b/.chloggen/1167.yaml new file mode 100644 index 0000000000..cc9655329e --- /dev/null +++ b/.chloggen/1167.yaml @@ -0,0 +1,4 @@ +change_type: bug_fix +component: http +note: "Relax requirement on when to set HTTP span status to Error from `MUST` to `SHOULD`." +issues: [1167, 1003] diff --git a/.chloggen/1200.yaml b/.chloggen/1200.yaml new file mode 100644 index 0000000000..9d40d16961 --- /dev/null +++ b/.chloggen/1200.yaml @@ -0,0 +1,6 @@ +change_type: enhancement +component: gen_ai +note: > + Rename `gen_ai.usage.prompt_tokens` to `gen_ai.usage.input_tokens` and `gen_ai.usage.completion_tokens` to `gen_ai.usage.output_tokens` + to align terminology between spans and metrics. +issues: [ 1200 ] diff --git a/.chloggen/1202.yaml b/.chloggen/1202.yaml new file mode 100644 index 0000000000..32e4265029 --- /dev/null +++ b/.chloggen/1202.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: gen_ai +note: Convert `gen_ai.operation.name` to enum and use it on spans +issues: [ 1202 ] diff --git a/.chloggen/1216.yaml b/.chloggen/1216.yaml new file mode 100644 index 0000000000..27b98da42a --- /dev/null +++ b/.chloggen/1216.yaml @@ -0,0 +1,5 @@ +change_type: breaking +component: tls +note: > + Deprecate `tls.client.server_name attribute` in favor of common `server.address`. +issues: [ 1211, 1216 ] diff --git a/.chloggen/1239.yaml b/.chloggen/1239.yaml new file mode 100644 index 0000000000..33a9ee75cb --- /dev/null +++ b/.chloggen/1239.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: network +note: Add QUIC to the list of well known network transports +issues: [ 1237, 1239 ] diff --git a/.chloggen/1241.yaml b/.chloggen/1241.yaml new file mode 100644 index 0000000000..a3af4264c3 --- /dev/null +++ b/.chloggen/1241.yaml @@ -0,0 +1,4 @@ +change_type: breaking +component: messaging +note: Deprecate `messaging.destination_publish.*`` namespace and remove all usages. +issues: [ 1178, 1241 ] diff --git a/.chloggen/1243.yaml b/.chloggen/1243.yaml new file mode 100644 index 0000000000..321a3dc7f4 --- /dev/null +++ b/.chloggen/1243.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: "`db.query.text` IN-clauses MAY be collapsed during the sanitization process" + +# 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: [ 1053 ] + +# (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/1244.yaml b/.chloggen/1244.yaml new file mode 100644 index 0000000000..849a02c9ff --- /dev/null +++ b/.chloggen/1244.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: db, messaging +note: Clarify that DB and messaging system-specific conventions override common ones +issues: [ 1235, 1244 ] diff --git a/.chloggen/1297.yaml b/.chloggen/1297.yaml new file mode 100644 index 0000000000..3b907728a4 --- /dev/null +++ b/.chloggen/1297.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: gen_ai +note: Add `server.address`, `server.port`, and `error.type` to GenAI spans. +issues: [ 1297 ] diff --git a/.chloggen/add_linux_memory_slab.yaml b/.chloggen/add_linux_memory_slab.yaml new file mode 100755 index 0000000000..ebc232861f --- /dev/null +++ b/.chloggen/add_linux_memory_slab.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: linux + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add the `system.linux.memory.slab.usage` metric and the `linux.memory.slab.state` 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: [531] + +# (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/cicd-reg-attr.yaml b/.chloggen/cicd-reg-attr.yaml new file mode 100755 index 0000000000..a50fe72f31 --- /dev/null +++ b/.chloggen/cicd-reg-attr.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: cicd, deployment, artifact, test, vcs + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Adds CICD common attributes to the 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: [915, 832, 833] + +# (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: | + - CICD common attributes have been added to the registry. + - `deployment.environment` has been deprecated and moved to `deployment.environment.name`. diff --git a/.chloggen/cloud-events-restructure.yaml b/.chloggen/cloud-events-restructure.yaml new file mode 100755 index 0000000000..90e15f3bc9 --- /dev/null +++ b/.chloggen/cloud-events-restructure.yaml @@ -0,0 +1,5 @@ +change_type: 'enhancement' +component: cloudevents +note: CloudEvents conventions to follow HTTP/Messaging Span conventions +issues: [654] +subtext: diff --git a/.chloggen/jvm_memory-buffer_metric_renaming.yaml b/.chloggen/jvm_memory-buffer_metric_renaming.yaml new file mode 100755 index 0000000000..19ef16c697 --- /dev/null +++ b/.chloggen/jvm_memory-buffer_metric_renaming.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: jvm + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: "Rename JVM metric `jvm.buffer.memory.usage` to `jvm.buffer.memory.used`" + +# 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: [288] + +# (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/log-original-body.yaml b/.chloggen/log-original-body.yaml new file mode 100755 index 0000000000..858bf4242e --- /dev/null +++ b/.chloggen/log-original-body.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: log + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add 'log.record.original' 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: [1137] + +# (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/v8js-metrics.yaml b/.chloggen/v8js-metrics.yaml new file mode 100644 index 0000000000..276a49d500 --- /dev/null +++ b/.chloggen/v8js-metrics.yaml @@ -0,0 +1,17 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: new_component + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: v8js + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Introducing semantic conventions for V8 JS Engine runtime metrics. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [990] diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index bce9f70428..de593477f3 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -23,7 +23,7 @@ /model/logs/ @open-telemetry/specs-semconv-approvers @tigrannajaryan /docs/exceptions/exceptions-logs.md @open-telemetry/specs-semconv-approvers @tigrannajaryan /docs/feature-flags/feature-flags-logs.md @open-telemetry/specs-semconv-approvers @tigrannajaryan -/docs/general/events-general.md @open-telemetry/specs-semconv-approvers @tigrannajaryan +/docs/general/events-general.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-event-approvers @tigrannajaryan /docs/general/logs-general.md @open-telemetry/specs-semconv-approvers @tigrannajaryan /docs/logs/ @open-telemetry/specs-semconv-approvers @tigrannajaryan @@ -88,4 +88,10 @@ /model/resource/process.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers /model/network.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers -# TODO - Add semconv area experts +# CICD semantic conventions approvers +/model/registry/artifact.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers +/model/registry/cicd.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers +/model/registry/code.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers +/model/registry/deployment.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers +/model/registry/test.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers +/model/registry/vcs.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index a9b17439f1..33808df8d6 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -20,9 +20,11 @@ body: # DO NOT manually edit it. # Start semconv area list - area:android + - area:artifact - area:aspnetcore - area:aws - area:browser + - area:cicd - area:client - area:cloud - area:cloudevents @@ -51,6 +53,7 @@ body: - area:http - area:jvm - area:k8s + - area:linux - area:log - area:messaging - area:network @@ -68,11 +71,14 @@ body: - area:source - area:system - area:telemetry + - area:test - area:thread - area:tls - area:url - area:user-agent - area:user + - area:v8js + - area:vcs - area:webengine # End semconv area list - type: textarea diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 1c4d197867..2c2be5b2a6 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -13,9 +13,11 @@ body: # DO NOT manually edit it. # Start semconv area list - area:android + - area:artifact - area:aspnetcore - area:aws - area:browser + - area:cicd - area:client - area:cloud - area:cloudevents @@ -44,6 +46,7 @@ body: - area:http - area:jvm - area:k8s + - area:linux - area:log - area:messaging - area:network @@ -61,11 +64,14 @@ body: - area:source - area:system - area:telemetry + - area:test - area:thread - area:tls - area:url - area:user-agent - area:user + - area:v8js + - area:vcs - area:webengine # End semconv area list - type: textarea diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index 3296a68a10..f6d4064985 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -22,9 +22,11 @@ body: # DO NOT manually edit it. # Start semconv area list - area:android + - area:artifact - area:aspnetcore - area:aws - area:browser + - area:cicd - area:client - area:cloud - area:cloudevents @@ -53,6 +55,7 @@ body: - area:http - area:jvm - area:k8s + - area:linux - area:log - area:messaging - area:network @@ -70,11 +73,14 @@ body: - area:source - area:system - area:telemetry + - area:test - area:thread - area:tls - area:url - area:user-agent - area:user + - area:v8js + - area:vcs - area:webengine # End semconv area list - type: textarea diff --git a/.github/workflows/scripts/prepare-new-issue.sh b/.github/workflows/scripts/prepare-new-issue.sh index c8af7d0b4a..6142e5b3b8 100755 --- a/.github/workflows/scripts/prepare-new-issue.sh +++ b/.github/workflows/scripts/prepare-new-issue.sh @@ -15,6 +15,14 @@ set -euo pipefail +OS=$(uname | tr '[:upper:]' '[:lower:]') + +if [[ "${OS}" == "darwin" ]]; then + SED="gsed" +else + SED="sed" +fi + if [[ -z "${ISSUE:-}" || -z "${BODY:-}" || -z "${OPENER:-}" ]]; then echo "Missing one of ISSUE, BODY, or OPENER, please ensure all are set." exit 0 @@ -25,7 +33,7 @@ AREAS_SECTION_START=$( (echo "${BODY}" | grep -n '### Area(s)' | awk '{ print $1 BODY_AREAS="" if [[ "${AREAS_SECTION_START}" != '-1' ]]; then - BODY_AREAS=$(echo "${BODY}" | sed -n $((AREAS_SECTION_START+2))p) + BODY_AREAS=$(echo "${BODY}" | "${SED}" -n $((AREAS_SECTION_START+2))p) fi for AREA in ${BODY_AREAS}; do diff --git a/.gitignore b/.gitignore index 46abe54e81..adbc11c813 100644 --- a/.gitignore +++ b/.gitignore @@ -34,4 +34,10 @@ package-lock.json .vscode # Visual Studio -.vs/ \ No newline at end of file +.vs/ + +# Python +venv + +# Brew package lock +Brewfile.lock.json diff --git a/.markdown_link_check_config.json b/.markdown_link_check_config.json index d16ec85009..6d5312790a 100644 --- a/.markdown_link_check_config.json +++ b/.markdown_link_check_config.json @@ -4,7 +4,7 @@ "pattern": "^https://github\\.com/open-telemetry/opentelemetry-specification/(issues|pull)" }, { - "pattern": "^https://github\\.com/open-telemetry/semantic-conventions/(issues|pull)" + "pattern": "^https://github\\.com/open-telemetry/semantic-conventions/(issues|pull|actions)" } ], "replacementPatterns": [ diff --git a/Brewfile b/Brewfile new file mode 100644 index 0000000000..63f9204b15 --- /dev/null +++ b/Brewfile @@ -0,0 +1 @@ +brew "gsed" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3e8f596ce..38bffd0f7c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -80,10 +80,17 @@ environment configured: npm install ``` +- If on MacOs, ensure you have `gsed` (GNU Sed) installed. If you have [HomeBrew](https://brew.sh) + installed, then you can run the following command to install GSED. + + ```bash + brew bundle + ``` + ### 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) +[Semantic Convention YAML Language](https://github.com/open-telemetry/build-tools/blob/v0.25.0/semantic-conventions/syntax.md) to learn how to make changes to the YAML files. #### Schema files diff --git a/Makefile b/Makefile index 1b6b4f499d..06e7b7d1b1 100644 --- a/Makefile +++ b/Makefile @@ -2,6 +2,14 @@ ALL_DOCS := $(shell find . -type f -name '*.md' -not -path './.github/*' -not -path './node_modules/*' | sort) PWD := $(shell pwd) +# Determine OS & Arch for specific OS only tools on Unix based systems +OS := $(shell uname | tr '[:upper:]' '[:lower:]') +ifeq ($(OS),darwin) + SED := gsed +else + SED := sed +endif + TOOLS_DIR := ./internal/tools MISSPELL_BINARY=bin/misspell @@ -13,8 +21,8 @@ CHLOGGEN_CONFIG := .chloggen/config.yaml # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates # Keep links in model/README.md and .vscode/settings.json in sync! -SEMCONVGEN_VERSION=0.24.0 -WEAVER_VERSION=0.2.0 +SEMCONVGEN_VERSION=0.25.0 +WEAVER_VERSION=0.7.0 # From where to resolve the containers (e.g. "otel/weaver"). CONTAINER_REPOSITORY=docker.io @@ -103,6 +111,15 @@ install-yamllint: yamllint: yamllint . +# Check semantic convention policies on YAML files +.PHONY: check-policies +check-policies: + docker run --rm -v $(PWD)/model:/source -v $(PWD)/policies:/policies -v $(PWD)/templates:/templates \ + otel/weaver:${WEAVER_VERSION} registry check \ + --registry=/source \ + --diagnostic-format=ansi \ + --policy=/policies/registry.rego + # Generate markdown tables from YAML definitions .PHONY: table-generation table-generation: @@ -151,7 +168,7 @@ table-check: # # .. which is why some additional processing is required to extract the # latest version number and strip off the "v" prefix. -LATEST_RELEASED_SEMCONV_VERSION := $(shell git ls-remote --tags https://github.com/open-telemetry/semantic-conventions.git | cut -f 2 | sort --reverse | head -n 1 | tr '/' ' ' | cut -d ' ' -f 3 | sed 's/v//g') +LATEST_RELEASED_SEMCONV_VERSION := $(shell git ls-remote --tags https://github.com/open-telemetry/semantic-conventions.git | cut -f 2 | sort --reverse | head -n 1 | tr '/' ' ' | cut -d ' ' -f 3 | $(SED) 's/v//g') .PHONY: compatibility-check compatibility-check: docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec --pull=always \ @@ -172,7 +189,7 @@ 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 check-format markdown-toc compatibility-check markdown-link-check attribute-registry-generation +check: misspell markdownlint check-format markdown-toc compatibility-check markdown-link-check check-policies 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" diff --git a/docs/README.md b/docs/README.md index 27c2c200a0..f31cc91fa5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -42,3 +42,5 @@ Semantic Conventions by signals: * [Metrics](general/metrics.md): Semantic Conventions for metrics. * [Resource](resource/README.md): Semantic Conventions for resources. * [Trace](general/trace.md): Semantic Conventions for traces and spans. + +Also see, [Non-normative supplementary information](non-normative/README.md). diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 2bab561397..5f981aae62 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -32,9 +32,11 @@ All registered attributes are listed by namespace in this registry. Currently, the following namespaces exist: - [Android](android.md) +- [Artifact](artifact.md) - [Aspnetcore](aspnetcore.md) - [AWS](aws.md) - [Browser](browser.md) +- [CICD](cicd.md) - [Client](client.md) - [Cloud](cloud.md) - [CloudEvents](cloudevents.md) @@ -65,6 +67,7 @@ Currently, the following namespaces exist: - [iOS](ios.md) - [JVM](jvm.md) - [K8s](k8s.md) +- [Linux](linux.md) - [Log](log.md) - [Messaging](messaging.md) - [Network](network.md) @@ -82,11 +85,14 @@ Currently, the following namespaces exist: - [Source](source.md) - [System](system.md) - [Telemetry](telemetry.md) +- [Test](test.md) - [Thread](thread.md) - [TLS](tls.md) - [URL](url.md) - [User](user.md) - [User Agent](user-agent.md) +- [V8js](v8js.md) +- [VCS](vcs.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 index c540e60cea..a8c442da77 100644 --- a/docs/attributes-registry/android.md +++ b/docs/attributes-registry/android.md @@ -6,8 +6,8 @@ # Android -- [Android](#android-attributes) -- [Android Deprecated](#android-deprecated-attributes) +- [Android Attributes](#android-attributes) +- [Deprecated Android Attributes](#deprecated-android-attributes) ## Android Attributes @@ -17,7 +17,7 @@ The Android platform on which the Android application is running. | ---------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------- | | `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 +## Deprecated Android Attributes This document defines attributes that represents an occurrence of a lifecycle transition on the Android platform. diff --git a/docs/attributes-registry/artifact.md b/docs/attributes-registry/artifact.md new file mode 100644 index 0000000000..fe6aa28a93 --- /dev/null +++ b/docs/attributes-registry/artifact.md @@ -0,0 +1,35 @@ + + + + + +# Artifact + +## Artifact Attributes + +This group describes attributes specific to artifacts. Artifacts are files or other immutable objects that are intended for distribution. This definition aligns directly with the [SLSA](https://slsa.dev/spec/v1.0/terminology#package-model) package model. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `artifact.attestation.filename` | string | The provenance filename of the built attestation which directly relates to the build artifact filename. This filename SHOULD accompany the artifact at publish time. See the [SLSA Relationship](https://slsa.dev/spec/v1.0/distributing-provenance#relationship-between-artifacts-and-attestations) specification for more information. | `golang-binary-amd64-v0.1.0.attestation`; `docker-image-amd64-v0.1.0.intoto.json1`; `release-1.tar.gz.attestation`; `file-name-package.tar.gz.intoto.json1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `artifact.attestation.hash` | string | The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), of the built attestation. Some envelopes in the software attestation space also refer to this as the [digest](https://github.com/in-toto/attestation/blob/main/spec/README.md#in-toto-attestation-framework-spec). | `1b31dfcd5b7f9267bf2ff47651df1cfb9147b9e4df1f335accf65b4cda498408` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `artifact.attestation.id` | string | The id of the build [software attestation](https://slsa.dev/attestation-model). | `123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `artifact.filename` | string | The human readable file name of the artifact, typically generated during build and release processes. Often includes the package name and version in the file name. [1] | `golang-binary-amd64-v0.1.0`; `docker-image-amd64-v0.1.0`; `release-1.tar.gz`; `file-name-package.tar.gz` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `artifact.hash` | string | The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), often found in checksum.txt on a release of the artifact and used to verify package integrity. [2] | `9ff4c52759e2c4ac70b7d517bc7fcdc1cda631ca0045271ddd1b192544f8a3e9` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `artifact.purl` | string | The [Package URL](https://github.com/package-url/purl-spec) of the [package artifact](https://slsa.dev/spec/v1.0/terminology#package-model) provides a standard way to identify and locate the packaged artifact. | `pkg:github/package-url/purl-spec@1209109710924`; `pkg:npm/foo@12.12.3` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `artifact.version` | string | The version of the artifact. | `v0.1.0`; `1.2.1`; `122691-build` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This file name can also act as the [Package Name](https://slsa.dev/spec/v1.0/terminology#package-model) +in cases where the package ecosystem maps accordingly. +Additionally, the artifact [can be published](https://slsa.dev/spec/v1.0/terminology#software-supply-chain) +for others, but that is not a guarantee. + +**[2]:** The specific algorithm used to create the cryptographic hash value is +not defined. In situations where an artifact has multiple +cryptographic hashes, it is up to the implementer to choose which +hash value to set here; this should be the most secure hash algorithm +that is suitable for the situation and consistent with the +corresponding attestation. The implementer can then provide the other +hash values through an additional set of attribute extensions as they +deem necessary. diff --git a/docs/attributes-registry/aspnetcore.md b/docs/attributes-registry/aspnetcore.md index 1fe1a2ad74..941c86fcb0 100644 --- a/docs/attributes-registry/aspnetcore.md +++ b/docs/attributes-registry/aspnetcore.md @@ -6,7 +6,7 @@ # Aspnetcore -## Aspnetcore Attributes +## ASP.NET Core Attributes ASP.NET Core attributes diff --git a/docs/attributes-registry/aws.md b/docs/attributes-registry/aws.md index fa4cf4deac..4d36c2e3c8 100644 --- a/docs/attributes-registry/aws.md +++ b/docs/attributes-registry/aws.md @@ -6,15 +6,15 @@ # 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) +- [General AWS Attributes](#general-aws-attributes) +- [Amazon DynamoDB Attributes](#amazon-dynamodb-attributes) +- [Amazon ECS Attributes](#amazon-ecs-attributes) +- [Amazon EKS Attributes](#amazon-eks-attributes) +- [Amazon Lambda Attributes](#amazon-lambda-attributes) +- [Amazon Logs Attributes](#amazon-logs-attributes) +- [Amazon S3 Attributes](#amazon-s3-attributes) -## AWS Attributes +## General AWS Attributes This document defines generic attributes for AWS services. @@ -22,7 +22,7 @@ This document defines generic attributes for AWS services. | ---------------- | ------ | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------- | | `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 +## Amazon DynamoDB Attributes This document defines attributes for AWS DynamoDB. @@ -51,7 +51,7 @@ This document defines attributes for AWS DynamoDB. | `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 +## Amazon ECS Attributes This document defines attributes for AWS Elastic Container Service (ECS). @@ -72,7 +72,7 @@ This document defines attributes for AWS Elastic Container Service (ECS). | `ec2` | ec2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `fargate` | fargate | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## AWS EKS Attributes +## Amazon EKS Attributes This document defines attributes for AWS Elastic Kubernetes Service (EKS). @@ -80,7 +80,7 @@ This document defines attributes for AWS Elastic Kubernetes Service (EKS). | --------------------- | ------ | -------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------- | | `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 +## Amazon Lambda Attributes This document defines attributes for AWS Lambda. @@ -90,7 +90,7 @@ This document defines attributes for AWS Lambda. **[1]:** This may be different from `cloud.resource_id` if an alias is involved. -## AWS Log Attributes +## Amazon Logs Attributes This document defines attributes for AWS Logs. @@ -107,7 +107,7 @@ This document defines attributes for AWS Logs. **[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 +## Amazon S3 Attributes This document defines attributes for AWS S3. diff --git a/docs/attributes-registry/cicd.md b/docs/attributes-registry/cicd.md new file mode 100644 index 0000000000..858bf01b96 --- /dev/null +++ b/docs/attributes-registry/cicd.md @@ -0,0 +1,28 @@ + + + + + +# CICD + +## CICD Pipeline Attributes + +This group describes attributes specific to pipelines within a Continuous Integration and Continuous Deployment (CI/CD) system. A [pipeline]() in this case is a series of steps that are performed in order to deliver a new version of software. This aligns with the [Britannica](https://www.britannica.com/dictionary/pipeline) definition of a pipeline where a **pipeline** is the system for developing and producing something. In the context of CI/CD, a pipeline produces or delivers software. + +| Attribute | Type | Description | Examples | Stability | +| --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `cicd.pipeline.name` | string | The human readable name of the pipeline within a CI/CD system. | `Build and Test`; `Lint`; `Deploy Go Project`; `deploy_to_environment` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cicd.pipeline.run.id` | string | The unique identifier of a pipeline run within a CI/CD system. | `120912` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cicd.pipeline.task.name` | string | The human readable name of a task within a pipeline. Task here most closely aligns with a [computing process]() in a pipeline. Other terms for tasks include commands, steps, and procedures. | `Run GoLang Linter`; `Go Build`; `go-test`; `deploy_binary` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cicd.pipeline.task.run.id` | string | The unique identifier of a task run within a pipeline. | `12097` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cicd.pipeline.task.run.url.full` | string | The [URL](https://en.wikipedia.org/wiki/URL) of the pipeline run providing the complete address in order to locate and identify the pipeline run. | `https://github.com/open-telemetry/semantic-conventions/actions/runs/9753949763/job/26920038674?pr=1075` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cicd.pipeline.task.type` | string | The type of the task within a pipeline. | `build`; `test`; `deploy` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`cicd.pipeline.task.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------- | ----------- | ---------------------------------------------------------------- | +| `build` | build | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `deploy` | deploy | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `test` | test | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/container.md b/docs/attributes-registry/container.md index fdca43d789..4aef8d3f91 100644 --- a/docs/attributes-registry/container.md +++ b/docs/attributes-registry/container.md @@ -6,8 +6,8 @@ # Container -- [Container](#container-attributes) -- [Container Deprecated](#container-deprecated-attributes) +- [Container Attributes](#container-attributes) +- [Deprecated Container Attributes](#deprecated-container-attributes) ## Container Attributes @@ -35,7 +35,7 @@ The ID is assigned by the container runtime and can vary in different environmen **[3]:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field. -## Container Deprecated Attributes +## Deprecated Container Attributes Describes deprecated container attributes. diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index db78b93f6b..066ca70bac 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -6,14 +6,14 @@ # 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) +- [General Database Attributes](#general-database-attributes) +- [Cassandra Attributes](#cassandra-attributes) +- [Azure Cosmos DB Attributes](#azure-cosmos-db-attributes) +- [Elasticsearch Attributes](#elasticsearch-attributes) +- [Deprecated Database Attributes](#deprecated-database-attributes) +- [Deprecated Database Metrics](#deprecated-database-metrics) -## Db Attributes +## General Database Attributes This group defines the attributes used to describe telemetry in the context of databases. @@ -118,7 +118,7 @@ Even though parameterized query text can potentially have sensitive data, by usi | `trino` | Trino | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `vertica` | Vertica | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Db Cassandra Attributes +## Cassandra Attributes This group defines attributes for Cassandra. @@ -147,7 +147,7 @@ This group defines attributes for Cassandra. | `three` | three | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `two` | two | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Db CosmosDB Attributes +## Azure Cosmos DB Attributes This group defines attributes for Azure Cosmos DB. @@ -188,7 +188,18 @@ This group defines attributes for Azure Cosmos DB. | `Replace` | replace | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `Upsert` | upsert | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Db Deprecated Attributes +## Elasticsearch Attributes + +This group defines attributes for Elasticsearch. + +| Attribute | Type | Description | Examples | Stability | +| ----------------------------------- | ------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [8] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[8]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names. + +## Deprecated Database Attributes "Describes deprecated db attributes." @@ -209,18 +220,7 @@ This group defines attributes for Azure Cosmos DB. | `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.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [8] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[8]:** 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 +## Deprecated Database Metrics "Describes deprecated db metrics attributes." diff --git a/docs/attributes-registry/deployment.md b/docs/attributes-registry/deployment.md index 97c68f3ebf..85fd31f339 100644 --- a/docs/attributes-registry/deployment.md +++ b/docs/attributes-registry/deployment.md @@ -6,18 +6,39 @@ # Deployment +- [Deployment Attributes](#deployment-attributes) +- [Deployment Deprecated Attributes](#deployment-deprecated-attributes) + ## 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) | +| Attribute | Type | Description | Examples | Stability | +| ----------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | ---------------------------------------------------------------- | +| `deployment.environment.name` | 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) | +| `deployment.id` | string | The id of the deployment. | `1208` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `deployment.name` | string | The name of the deployment. | `deploy my app`; `deploy-frontend` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `deployment.status` | string | The status of the deployment. | `failed`; `succeeded` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** `deployment.environment` does not affect the uniqueness constraints defined through +**[1]:** `deployment.environment.name` does not affect the uniqueness constraints defined through the `service.namespace`, `service.name` and `service.instance.id` resource attributes. This implies that resources carrying the following attribute combinations MUST be considered to be identifying the same service: -- `service.name=frontend`, `deployment.environment=production` -- `service.name=frontend`, `deployment.environment=staging`. +- `service.name=frontend`, `deployment.environment.name=production` +- `service.name=frontend`, `deployment.environment.name=staging`. + +`deployment.status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ----------- | ----------- | ---------------------------------------------------------------- | +| `failed` | failed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `succeeded` | succeeded | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Deployment Deprecated Attributes + +"Describes deprecated deployment attributes." + +| Attribute | Type | Description | Examples | Stability | +| ------------------------ | ------ | -------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------- | +| `deployment.environment` | string | 'Deprecated, use `deployment.environment.name` instead.' | `staging`; `production` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, use `deployment.environment.name` instead. | diff --git a/docs/attributes-registry/dns.md b/docs/attributes-registry/dns.md index 6345d59240..a03b3cef57 100644 --- a/docs/attributes-registry/dns.md +++ b/docs/attributes-registry/dns.md @@ -6,7 +6,7 @@ # Dns -## Dns Attributes +## DNS Attributes This document defines the shared attributes used to report a DNS query. diff --git a/docs/attributes-registry/enduser.md b/docs/attributes-registry/enduser.md index 66ba5a0d1e..db2d7a5835 100644 --- a/docs/attributes-registry/enduser.md +++ b/docs/attributes-registry/enduser.md @@ -6,7 +6,7 @@ # Enduser -## Enduser Deprecated Attributes +## Deprecated End User Attributes Describes deprecated enduser attributes. Complete enduser namespace has been deprecated diff --git a/docs/attributes-registry/faas.md b/docs/attributes-registry/faas.md index 26a1200ece..6279999b71 100644 --- a/docs/attributes-registry/faas.md +++ b/docs/attributes-registry/faas.md @@ -6,7 +6,7 @@ # Faas -## Faas Attributes +## Function as a Service Attributes FaaS attributes diff --git a/docs/attributes-registry/gcp.md b/docs/attributes-registry/gcp.md index cade703150..04f6f981bf 100644 --- a/docs/attributes-registry/gcp.md +++ b/docs/attributes-registry/gcp.md @@ -6,10 +6,10 @@ # GCP -- [Gcp](#gcp-attributes) -- [Gcp Client](#gcp-client-attributes) -- [Gcp Cloud Run](#gcp-cloud-run-attributes) -- [Gcp Gce](#gcp-gce-attributes) +- [GCP Attributes](#gcp-attributes) +- [GCP Client Attributes](#gcp-client-attributes) +- [GCP - Google Cloud Run Attributes](#gcp---google-cloud-run-attributes) +- [GCP - Google Compute Engine (GCE) Attributes](#gcp---google-compute-engine-gce-attributes) ## GCP Attributes @@ -28,7 +28,7 @@ Attributes for Google Cloud client libraries. **[1]:** Intended to be a stable identifier for Google Cloud client libraries that is uniform across implementation languages. The value should be derived from the canonical service domain for the service; for example, 'foo.googleapis.com' should result in a value of 'foo'. -## GCP Cloud Run Attributes +## GCP - Google Cloud Run Attributes This document defines attributes for Google Cloud Run. @@ -37,7 +37,7 @@ This document defines attributes for Google Cloud Run. | `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 +## GCP - Google Compute Engine (GCE) Attributes This document defines attributes for Google Compute Engine (GCE). diff --git a/docs/attributes-registry/gen-ai.md b/docs/attributes-registry/gen-ai.md index 7030cb3bd3..d136ebf575 100644 --- a/docs/attributes-registry/gen-ai.md +++ b/docs/attributes-registry/gen-ai.md @@ -6,15 +6,18 @@ # Gen AI -## Gen AI Attributes +- [GenAI Attributes](#genai-attributes) +- [Deprecated GenAI Attributes](#deprecated-genai-attributes) + +## GenAI Attributes This document defines the attributes used to describe telemetry in the context of Generative Artificial Intelligence (GenAI) Models requests and responses. | Attribute | Type | Description | Examples | Stability | | ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------- | | `gen_ai.completion` | string | The full response received from the GenAI model. [1] | `[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.operation.name` | string | The name of the operation being performed. | `chat`; `completion` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.prompt` | string | The full prompt sent to the GenAI model. [2] | `[{'role': 'user', 'content': 'What is the capital of France?'}]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.operation.name` | string | The name of the operation being performed. [2] | `chat`; `text_completion` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.prompt` | string | The full prompt sent to the GenAI model. [3] | `[{'role': 'user', 'content': 'What is the capital of France?'}]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.request.frequency_penalty` | double | The frequency penalty setting for the GenAI request. | `0.1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.request.max_tokens` | int | The maximum number of tokens the model generates for a request. | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.request.model` | string | The name of the GenAI model a request is being made to. | `gpt-4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -26,17 +29,33 @@ This document defines the attributes used to describe telemetry in the context o | `gen_ai.response.finish_reasons` | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.response.id` | string | The unique identifier for the completion. | `chatcmpl-123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.response.model` | string | The name of the model that generated the response. | `gpt-4-0613` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.system` | string | The Generative AI product as identified by the client or server instrumentation. [3] | `openai` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.system` | string | The Generative AI product as identified by the client or server instrumentation. [4] | `openai` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.token.type` | string | The type of token being counted. | `input`; `output` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.usage.completion_tokens` | int | The number of tokens used in the GenAI response (completion). | `180` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.usage.prompt_tokens` | int | The number of tokens used in the GenAI input or prompt. | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.usage.input_tokens` | int | The number of tokens used in the GenAI input (prompt). | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.usage.output_tokens` | int | The number of tokens used in the GenAI response (completion). | `180` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) -**[2]:** It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) +**[2]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. + +**[3]:** It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + +**[4]:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. -**[3]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. -For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. +`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. @@ -53,3 +72,12 @@ For custom model, a custom friendly name SHOULD be used. If none of these option | -------- | ------------------------------------------ | ---------------------------------------------------------------- | | `input` | Input tokens (prompt, input, etc.) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `output` | Output tokens (completion, response, etc.) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Deprecated GenAI Attributes + +Describes deprecated `gen_ai` attributes. + +| Attribute | Type | Description | Examples | Stability | +| -------------------------------- | ---- | ----------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | +| `gen_ai.usage.completion_tokens` | int | Deprecated, use `gen_ai.usage.output_tokens` instead. | `42` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `gen_ai.usage.output_tokens` attribute. | +| `gen_ai.usage.prompt_tokens` | int | Deprecated, use `gen_ai.usage.input_tokens` instead. | `42` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `gen_ai.usage.input_tokens` attribute. | diff --git a/docs/attributes-registry/http.md b/docs/attributes-registry/http.md index 7d33288aef..069666a943 100644 --- a/docs/attributes-registry/http.md +++ b/docs/attributes-registry/http.md @@ -6,8 +6,8 @@ # HTTP -- [Http](#http-attributes) -- [Http Deprecated](#http-deprecated-attributes) +- [HTTP Attributes](#http-attributes) +- [Deprecated HTTP Attributes](#deprecated-http-attributes) ## HTTP Attributes @@ -78,7 +78,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -## HTTP Deprecated Attributes +## Deprecated HTTP Attributes Describes deprecated HTTP attributes. diff --git a/docs/attributes-registry/ios.md b/docs/attributes-registry/ios.md index f15cf13d6a..a8891cdcbd 100644 --- a/docs/attributes-registry/ios.md +++ b/docs/attributes-registry/ios.md @@ -6,7 +6,7 @@ # iOS -## iOS Deprecated Attributes +## Deprecated iOS Attributes The iOS platform on which the iOS application is running. diff --git a/docs/attributes-registry/jvm.md b/docs/attributes-registry/jvm.md index 70f08089d7..75f1f3093a 100644 --- a/docs/attributes-registry/jvm.md +++ b/docs/attributes-registry/jvm.md @@ -6,7 +6,7 @@ # JVM -## JVM Attributes +## Java Virtual Machine (JVM) Attributes This document defines Java Virtual machine related attributes. diff --git a/docs/attributes-registry/k8s.md b/docs/attributes-registry/k8s.md index b9bc225333..34d2e64c88 100644 --- a/docs/attributes-registry/k8s.md +++ b/docs/attributes-registry/k8s.md @@ -6,10 +6,10 @@ # K8s -- [K8s](#k8s-attributes) -- [K8s Deprecated](#k8s-deprecated-attributes) +- [Kubernetes Attributes](#kubernetes-attributes) +- [Deprecated Kubernetes Attributes](#deprecated-kubernetes-attributes) -## K8s Attributes +## Kubernetes Attributes Kubernetes resource attributes. @@ -63,7 +63,7 @@ Which states: Therefore, UIDs between clusters should be extremely unlikely to conflict. -## K8s Deprecated Attributes +## Deprecated Kubernetes Attributes Describes deprecated k8s attributes. diff --git a/docs/attributes-registry/linux.md b/docs/attributes-registry/linux.md new file mode 100644 index 0000000000..cf817efa8e --- /dev/null +++ b/docs/attributes-registry/linux.md @@ -0,0 +1,22 @@ + + + + + +# Linux + +## Linux Memory Attributes + +Describes Linux Memory attributes + +| Attribute | Type | Description | Examples | Stability | +| ------------------------- | ------ | --------------------------- | ------------------------------ | ---------------------------------------------------------------- | +| `linux.memory.slab.state` | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`linux.memory.slab.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --------------- | ------------- | ---------------------------------------------------------------- | +| `reclaimable` | reclaimable | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unreclaimable` | unreclaimable | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/log.md b/docs/attributes-registry/log.md index 837a982cb5..c24c22b1ac 100644 --- a/docs/attributes-registry/log.md +++ b/docs/attributes-registry/log.md @@ -6,11 +6,11 @@ # Log -- [Log](#log-attributes) -- [Log File](#log-file-attributes) -- [Log Record](#log-record-attributes) +- [General Log Attributes](#general-log-attributes) +- [Log File Attributes](#log-file-attributes) +- [Log Record Attributes](#log-record-attributes) -## Log Attributes +## General Log Attributes This document defines log attributes @@ -40,9 +40,12 @@ Attributes for a file to which log was emitted. 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) | +| Attribute | Type | Description | Examples | Stability | +| --------------------- | ------ | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `log.record.original` | string | The complete orignal Log Record. [1] | `77 <86>1 2015-08-06T21:58:59.694Z 192.168.2.133 inactive - - - Something happened`; `[INFO] 8/3/24 12:34:56 Something happened` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `log.record.uid` | string | A unique identifier for the Log Record. [2] | `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. +**[1]:** This value MAY be added when processing a Log Record which was originally transmitted as a string or equivalent data type AND the Body field of the Log Record does not contain the same value. (e.g. a syslog or a log record read from a file.) + +**[2]:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values. The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), but other identifiers (e.g. UUID) may be used as needed. diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index dd69d0c13e..47fff29b16 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -6,16 +6,16 @@ # 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) +- [General Messaging Attributes](#general-messaging-attributes) +- [Azure Event Hubs Attributes](#azure-event-hubs-attributes) +- [GCP Pub/Sub Attributes](#gcp-pubsub-attributes) +- [Kafka Attributes](#kafka-attributes) +- [RabbitMQ Attributes](#rabbitmq-attributes) +- [RocketMQ Attributes](#rocketmq-attributes) +- [Azure Service Bus Attributes](#azure-service-bus-attributes) +- [Deprecated Messaging Attributes](#deprecated-messaging-attributes) -## Messaging Attributes +## General Messaging Attributes Attributes describing telemetry around messaging systems and messaging activities. @@ -30,15 +30,13 @@ Attributes describing telemetry around messaging systems and messaging activitie | `messaging.destination.subscription.name` | string | The name of the destination subscription from which a message is consumed. [4] | `subscription-a` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [5] | `/customers/{customerId}` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.destination.temporary` | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.destination_publish.anonymous` | boolean | A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name). | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.destination_publish.name` | string | The name of the original destination the message was published to [6] | `MyQueue`; `MyTopic` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.message.body.size` | int | The size of the message body in bytes. [7] | `1439` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.message.body.size` | int | The size of the message body in bytes. [6] | `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. [8] | `2738` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [7] | `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. [9] | `publish`; `create`; `receive` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.system` | string | The messaging system as identified by the client instrumentation. [10] | `activemq`; `aws_sqs`; `eventgrid` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.operation.type` | string | A string identifying the type of the messaging operation. [8] | `publish`; `create`; `receive` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.system` | string | The messaging system as identified by the client instrumentation. [9] | `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. @@ -51,18 +49,15 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi **[5]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. -**[6]:** 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. - -**[7]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed +**[6]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed body size should be used. -**[8]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed +**[7]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed size should be used. -**[9]:** If a custom value is used, it MUST be of low cardinality. +**[8]:** If a custom value is used, it MUST be of low cardinality. -**[10]:** The actual messaging system may differ from the one known by the client. For example, when using Kafka client libraries to communicate with Azure Event Hubs, the `messaging.system` is set to `kafka` based on the instrumentation's best knowledge. +**[9]:** The actual messaging system may differ from the one known by the client. For example, when using Kafka client libraries to communicate with Azure Event Hubs, the `messaging.system` is set to `kafka` based on the instrumentation's best knowledge. `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. @@ -91,21 +86,7 @@ size should be used. | `rocketmq` | Apache RocketMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `servicebus` | Azure Service Bus | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Messaging Deprecated Attributes - -Describes deprecated messaging attributes. - -| Attribute | Type | Description | Examples | Stability | -| ---------------------------------------------------- | ------ | ----------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `messaging.client_id` | string | Deprecated, use `messaging.client.id` instead. | `client-5`; `myhost@8742@s8083jm` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.client.id`. | -| `messaging.eventhubs.consumer.group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `$Default` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name`. | -| `messaging.kafka.consumer.group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `my-group` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name`. | -| `messaging.kafka.destination.partition` | int | Deprecated, use `messaging.destination.partition.id` instead. | `2` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.destination.partition.id`. | -| `messaging.operation` | string | Deprecated, use `messaging.operation.type` instead. | `publish`; `create`; `process` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.operation.type`. | -| `messaging.rocketmq.client_group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `myConsumerGroup` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name` on the consumer spans. No replacement for producer spans. | -| `messaging.servicebus.destination.subscription_name` | string | Deprecated, use `messaging.servicebus.destination.subscription_name` instead. | `subscription-a` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.servicebus.destination.subscription_name`. | - -## Messaging Eventhubs Attributes +## Azure Event Hubs Attributes This group describes attributes specific to Azure Event Hubs. @@ -113,7 +94,7 @@ This group describes attributes specific to Azure Event Hubs. | ------------------------------------------- | ---- | -------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------- | | `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 +## GCP Pub/Sub Attributes This group describes attributes specific to GCP Pub/Sub. @@ -124,19 +105,19 @@ This group describes attributes specific to GCP Pub/Sub. | `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 +## Kafka Attributes This group describes attributes specific to Apache Kafka. | Attribute | Type | Description | Examples | Stability | | ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------- | -| `messaging.kafka.message.key` | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [11] | `myKey` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.kafka.message.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.kafka.message.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. [10] | `myKey` | ![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) | +| `messaging.kafka.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[11]:** If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value. +**[10]:** If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value. -## Messaging RabbitMQ Attributes +## RabbitMQ Attributes This group describes attributes specific to RabbitMQ. @@ -145,7 +126,7 @@ This group describes attributes specific to RabbitMQ. | `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 +## RocketMQ Attributes This group describes attributes specific to RocketMQ. @@ -176,7 +157,7 @@ This group describes attributes specific to RocketMQ. | `normal` | Normal message | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `transaction` | Transaction message | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Messaging Servicebus Attributes +## Azure Service Bus Attributes This group describes attributes specific to Azure Service Bus. @@ -194,3 +175,20 @@ This group describes attributes specific to Azure Service Bus. | `complete` | Message is completed | ![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) | + +## Deprecated Messaging Attributes + +Describes deprecated messaging attributes. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------------------------------------- | ------- | ----------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `messaging.client_id` | string | Deprecated, use `messaging.client.id` instead. | `client-5`; `myhost@8742@s8083jm` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.client.id`. | +| `messaging.destination_publish.anonymous` | boolean | Deprecated, no replacement at this time. | | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
No replacement at this time. | +| `messaging.destination_publish.name` | string | Deprecated, no replacement at this time. | `MyQueue`; `MyTopic` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
No replacement at this time. | +| `messaging.eventhubs.consumer.group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `$Default` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name`. | +| `messaging.kafka.consumer.group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `my-group` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name`. | +| `messaging.kafka.destination.partition` | int | Deprecated, use `messaging.destination.partition.id` instead. | `2` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.destination.partition.id`. | +| `messaging.kafka.message.offset` | int | Deprecated, use `messaging.kafka.offset` instead. | `42` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.kafka.offset`. | +| `messaging.operation` | string | Deprecated, use `messaging.operation.type` instead. | `publish`; `create`; `process` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.operation.type`. | +| `messaging.rocketmq.client_group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `myConsumerGroup` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name` on the consumer spans. No replacement for producer spans. | +| `messaging.servicebus.destination.subscription_name` | string | Deprecated, use `messaging.servicebus.destination.subscription_name` instead. | `subscription-a` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.servicebus.destination.subscription_name`. | diff --git a/docs/attributes-registry/network.md b/docs/attributes-registry/network.md index 54bf6099f8..15375fb86b 100644 --- a/docs/attributes-registry/network.md +++ b/docs/attributes-registry/network.md @@ -6,8 +6,8 @@ # Network -- [Network](#network-attributes) -- [Network Deprecated](#network-deprecated-attributes) +- [Network Attributes](#network-attributes) +- [Deprecated Network Attributes](#deprecated-network-attributes) ## Network Attributes @@ -88,12 +88,13 @@ 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 | -| ------ | ------------------------ | ---------------------------------------------------------- | -| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| Value | Description | Stability | +| ------ | ------------------------ | ---------------------------------------------------------------- | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![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. @@ -102,7 +103,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -## Network Deprecated Attributes +## Deprecated Network Attributes These attributes may be used for any network related operation. diff --git a/docs/attributes-registry/oci.md b/docs/attributes-registry/oci.md index 6a2aa64c15..c528a50fcb 100644 --- a/docs/attributes-registry/oci.md +++ b/docs/attributes-registry/oci.md @@ -6,7 +6,7 @@ # OCI -## OCI Manifest Attributes +## Open Container Initiative (OCI) Attributes An OCI image manifest. diff --git a/docs/attributes-registry/os.md b/docs/attributes-registry/os.md index 8785622356..a5b4f44ce8 100644 --- a/docs/attributes-registry/os.md +++ b/docs/attributes-registry/os.md @@ -6,7 +6,7 @@ # OS -## OS Attributes +## Operating System Attributes The operating system (OS) on which the process represented by this resource is running. diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md index 5ac726e13d..07ed204dc1 100644 --- a/docs/attributes-registry/otel.md +++ b/docs/attributes-registry/otel.md @@ -6,9 +6,9 @@ # OTel -- [Otel](#otel-attributes) -- [Otel Library Deprecated](#otel-library-deprecated-attributes) -- [Otel Scope](#otel-scope-attributes) +- [OTel Attributes](#otel-attributes) +- [OTel Scope Attributes](#otel-scope-attributes) +- [Deprecated OTel Library Attributes](#deprecated-otel-library-attributes) ## OTel Attributes @@ -26,15 +26,6 @@ Attributes reserved for OpenTelemetry | `ERROR` | The operation contains an error. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `OK` | The operation has been validated by an Application developer or Operator to have completed successfully. | ![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. @@ -43,3 +34,12 @@ Attributes used by non-OTLP exporters to represent OpenTelemetry Scope's concept | -------------------- | ------ | ------------------------------------------------------------------------------------ | ---------------------------------- | ---------------------------------------------------------- | | `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) | + +## Deprecated OTel Library 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. | diff --git a/docs/attributes-registry/process.md b/docs/attributes-registry/process.md index 6522b0ace3..922286f11d 100644 --- a/docs/attributes-registry/process.md +++ b/docs/attributes-registry/process.md @@ -6,8 +6,8 @@ # Process -- [Process](#process-attributes) -- [Process Deprecated](#process-deprecated-attributes) +- [Process Attributes](#process-attributes) +- [Deprecated Process Attributes](#deprecated-process-attributes) ## Process Attributes @@ -33,7 +33,7 @@ An operating system process. | `process.real_user.id` | int | The real user ID (RUID) of the process. | `1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `process.real_user.name` | string | The username of the real user of the process. | `operator` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `process.runtime.description` | string | An additional description about the runtime of the process, for example a specific vendor customization of the runtime environment. | `Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `process.runtime.name` | string | The name of the runtime of this process. For compiled native binaries, this SHOULD be the name of the compiler. | `OpenJDK Runtime Environment` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.runtime.name` | string | The name of the runtime of this process. | `OpenJDK Runtime Environment` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `process.runtime.version` | string | The version of the runtime of this process, as returned by the runtime without modification. | `14.0.2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `process.saved_user.id` | int | The saved user ID (SUID) of the process. | `1002` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `process.saved_user.name` | string | The username of the saved user. | `operator` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -58,7 +58,7 @@ An operating system process. | `major` | major | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `minor` | minor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Process Deprecated Attributes +## Deprecated Process Attributes Deprecated process attributes. diff --git a/docs/attributes-registry/rpc.md b/docs/attributes-registry/rpc.md index 561e7c27bc..9c6088a1ce 100644 --- a/docs/attributes-registry/rpc.md +++ b/docs/attributes-registry/rpc.md @@ -6,10 +6,10 @@ # RPC -- [Rpc](#rpc-attributes) -- [Rpc Deprecated](#rpc-deprecated-attributes) +- [Remote Procedure Call (RPC) Attributes](#remote-procedure-call-rpc-attributes) +- [Deprecated RPC Attributes](#deprecated-rpc-attributes) -## RPC Attributes +## Remote Procedure Call (RPC) Attributes This document defines attributes for remote procedure calls. @@ -107,7 +107,7 @@ This document defines attributes for remote procedure calls. | `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## RPC Deprecated Attributes +## Deprecated RPC Attributes Deprecated rpc message attributes. diff --git a/docs/attributes-registry/system.md b/docs/attributes-registry/system.md index c504f989f9..60871019ba 100644 --- a/docs/attributes-registry/system.md +++ b/docs/attributes-registry/system.md @@ -6,16 +6,16 @@ # 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) +- [General System Attributes](#general-system-attributes) +- [System CPU Attributes](#system-cpu-attributes) +- [Filesystem Attributes](#filesystem-attributes) +- [System Memory Attributes](#system-memory-attributes) +- [System Network Attributes](#system-network-attributes) +- [System Paging Attributes](#system-paging-attributes) +- [System Process Attributes](#system-process-attributes) +- [Deprecated System Attributes](#deprecated-system-attributes) -## System Attributes +## General System Attributes Describes System attributes @@ -31,37 +31,7 @@ Describes System CPU attributes | --------------------------- | ---- | ------------------------------- | -------- | ---------------------------------------------------------------- | | `system.cpu.logical_number` | int | The logical CPU number [0..n-1] | `1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## System Deprecated Attributes - -Deprecated system attributes. - -| Attribute | Type | Description | Examples | Stability | -| ------------------------- | ------ | ------------------------------------------------ | ------------------- | --------------------------------------------------------------------------------------------------- | -| `system.cpu.state` | string | Deprecated, use `cpu.mode` instead. | `idle`; `interrupt` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `cpu.mode` | -| `system.processes.status` | string | Deprecated, use `system.process.status` instead. | `running` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `system.process.status`. | - -`system.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -| ----------- | ----------- | ---------------------------------------------------------------- | -| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -`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 | -| ---------- | ----------- | ---------------------------------------------------------------- | -| `defunct` | defunct | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `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) | - -## System Filesystem Attributes +## Filesystem Attributes Describes Filesystem attributes @@ -181,3 +151,33 @@ Describes System Process attributes | `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) | + +## Deprecated System Attributes + +Deprecated system attributes. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------- | ------ | ------------------------------------------------ | ------------------- | --------------------------------------------------------------------------------------------------- | +| `system.cpu.state` | string | Deprecated, use `cpu.mode` instead. | `idle`; `interrupt` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `cpu.mode` | +| `system.processes.status` | string | Deprecated, use `system.process.status` instead. | `running` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `system.process.status`. | + +`system.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ----------- | ----------- | ---------------------------------------------------------------- | +| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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 | +| ---------- | ----------- | ---------------------------------------------------------------- | +| `defunct` | defunct | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `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) | diff --git a/docs/attributes-registry/test.md b/docs/attributes-registry/test.md new file mode 100644 index 0000000000..c8ad68977b --- /dev/null +++ b/docs/attributes-registry/test.md @@ -0,0 +1,36 @@ + + + + + +# Test + +## Test Attributes + +This group describes attributes specific to [software tests](https://en.wikipedia.org/wiki/Software_testing). + +| Attribute | Type | Description | Examples | Stability | +| ------------------------- | ------ | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `test.case.name` | string | The fully qualified human readable name of the [test case](https://en.wikipedia.org/wiki/Test_case). | `org.example.TestCase1.test1`; `example/tests/TestCase1.test1`; `ExampleTestCase1_test1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `test.case.result.status` | string | The status of the actual test case result from test execution. | `pass`; `fail` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `test.suite.name` | string | The human readable name of a [test suite](https://en.wikipedia.org/wiki/Test_suite). | `TestSuite1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `test.suite.run.status` | string | The status of the test suite run. | `success`; `failure`; `skipped`; `aborted`; `timed_out`; `in_progress` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`test.case.result.status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------ | ----------- | ---------------------------------------------------------------- | +| `fail` | fail | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pass` | pass | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`test.suite.run.status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------------- | ----------- | ---------------------------------------------------------------- | +| `aborted` | aborted | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `failure` | failure | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `in_progress` | in_progress | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `skipped` | skipped | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `success` | success | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `timed_out` | timed_out | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/tls.md b/docs/attributes-registry/tls.md index e6cdb56b19..1e030397e3 100644 --- a/docs/attributes-registry/tls.md +++ b/docs/attributes-registry/tls.md @@ -6,6 +6,9 @@ # TLS +- [TLS Attributes](#tls-attributes) +- [TLS Deprecated Attributes](#tls-deprecated-attributes) + ## TLS Attributes This document defines semantic convention attributes in the TLS namespace. @@ -22,7 +25,6 @@ This document defines semantic convention attributes in the TLS namespace. | `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) | @@ -50,3 +52,11 @@ This document defines semantic convention attributes in the TLS namespace. | ----- | ----------- | ---------------------------------------------------------------- | | `ssl` | ssl | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tls` | tls | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## TLS Deprecated Attributes + +Describes deprecated `tls` attributes. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------ | ------ | ----------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------- | +| `tls.client.server_name` | string | Deprecated, use `server.address` instead. | `opentelemetry.io` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `server.address. | diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md index 34b0c71f89..b7a10cd630 100644 --- a/docs/attributes-registry/user-agent.md +++ b/docs/attributes-registry/user-agent.md @@ -6,7 +6,7 @@ # User Agent -## User Agent Attributes +## User-agent Attributes Describes user-agent attributes. diff --git a/docs/attributes-registry/v8js.md b/docs/attributes-registry/v8js.md new file mode 100644 index 0000000000..a8ae0bff7a --- /dev/null +++ b/docs/attributes-registry/v8js.md @@ -0,0 +1,37 @@ + + + + + +# V8js + +## V8 JS Attributes + +Describes V8 JS Engine Runtime related attributes. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------- | ------ | ---------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------- | +| `v8js.gc.type` | string | The type of garbage collection. | `major`; `minor`; `incremental` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `v8js.heap.space.name` | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + +`v8js.gc.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------------- | ---------------------------------------- | ---------------------------------------------------------------- | +| `incremental` | Incremental (Incremental Marking). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `major` | Major (Mark Sweep Compact). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `minor` | Minor (Scavenge). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `weakcb` | Weak Callbacks (Process Weak Callbacks). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`v8js.heap.space.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------------------- | -------------------------- | ---------------------------------------------------------------- | +| `code_space` | Code memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/vcs.md b/docs/attributes-registry/vcs.md new file mode 100644 index 0000000000..0e11f9b2bf --- /dev/null +++ b/docs/attributes-registry/vcs.md @@ -0,0 +1,37 @@ + + + + + +# VCS + +## VCS Repository Attributes + +This group defines the attributes for [Version Control Systems (VCS)](https://en.wikipedia.org/wiki/Version_control). + +| Attribute | Type | Description | Examples | Stability | +| ----------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | +| `vcs.repository.change.id` | string | The ID of the change (pull request/merge request) if applicable. This is usually a unique (within repository) identifier generated by the VCS system. | `123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.repository.change.title` | string | The human readable title of the change (pull request/merge request). This title is often a brief summary of the change and may get merged in to a ref as the commit summary. | `Fixes broken thing`; `feat: add my new feature`; `[chore] update dependency` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.repository.ref.name` | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.repository.ref.revision` | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [1] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.repository.ref.type` | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.repository.url.full` | string | The [URL](https://en.wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), +of the recorded change to a ref within a repository pointing to a +commit [commit](https://git-scm.com/docs/git-commit) object. It does +not necessarily have to be a hash; it can simply define a +[revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) +which is an integer that is monotonically increasing. In cases where +it is identical to the `ref.name`, it SHOULD still be included. It is +up to the implementer to decide which value to set as the revision +based on the VCS system and situational context. + +`vcs.repository.ref.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | +| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/webengine.md b/docs/attributes-registry/webengine.md index be5955444e..1cb10ac3fb 100644 --- a/docs/attributes-registry/webengine.md +++ b/docs/attributes-registry/webengine.md @@ -6,7 +6,7 @@ # Webengine -## Webengine Attributes +## Web Engine Attributes This document defines the attributes used to describe the packaged software running the application code. diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md index 84e003d360..c9857d47fb 100644 --- a/docs/cloud-providers/aws-sdk.md +++ b/docs/cloud-providers/aws-sdk.md @@ -15,7 +15,7 @@ Some descriptions are also provided for populating general OpenTelemetry semanti ## Context Propagation -See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation). +See [compatibility](../non-normative/compatibility/aws.md#context-propagation). ## Common Attributes diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md index ca5ea0d0e6..79672b8e15 100644 --- a/docs/cloudevents/cloudevents-spans.md +++ b/docs/cloudevents/cloudevents-spans.md @@ -11,12 +11,8 @@ linkTitle: CloudEvents Spans - [Definitions](#definitions) -- [Overview](#overview) - [Conventions](#conventions) - - [Spans](#spans) - - [Creation](#creation) - - [Processing](#processing) - - [Attributes](#attributes) +- [Span attributes](#span-attributes) @@ -35,168 +31,20 @@ consult the [CloudEvents Primer](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/primer.md) document. -## Overview - -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](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. - -Consider the following scenario: - -``` -+----------+ +--------------+ -| Producer | ---------------> | Intermediary | -+----------+ +--------------+ - | - | - | - v -+----------+ +----------+ -| Consumer | <----------------- | Queue | -+----------+ +----------+ -``` - -With the traditional parent-child trace model, the above scenario would produce -two traces, completely independent from each other because the consumer -starts receiving (and thus has to specify a parent span) before it receives the event. -It is not possible to correlate a producer with a consumer(s) solely via a parent-child relationship. - -``` -+-------------------------------------------------+ -| Trace 1 | -| | -| +---------------------------------------+ | -| | Send (auto-instr) | | -| +---------------------------------------+ | -| +------------------------------------+ | -| | Intermediary: Received (auto-instr)| | -| +------------------------------------+ | -| +------------------------------------+ | -| | Intermediary: Send (auto-instr) | | -| +------------------------------------+ | -| | -| Trace 2 | -| | -| +---------------------------------------+ | -| | Consumer: Receive (auto-instr) | | -| +---------------------------------------+ | -| | -+-------------------------------------------------+ -``` - -This document defines semantic conventions to model the different stages -a CloudEvent can go through in a system, making it possible to create traces -that are meaningful and consistent. It covers creation, processing, -context propagation between producer and consumer(s) and attributes -to be added to spans. - -With the proposed model, it is possible to have an overview of everything -that happened as the result of an event. One can, for example, answer the -following questions: - -- What components in a system reacted to an event -- What further events were sent due to an incoming event -- Which event caused the exception - -With the conventions in this document, the application scenario above would -produce a trace where it is possible to correlate a producer with a consumer(s): - -``` -+-------------------------------------------------------+ -| Trace 1 | -| | -| +---------------------------------------+ | -| +---> | Create event | | -| | +---------------------------------------+ | -| | +---------------------------------------+ | -| | | Send (auto-instr) | | -| | +---------------------------------------+ | -| | +------------------------------------+ | -| | | Intermediary: Received (auto-instr)| | -| | +------------------------------------+ | -| | +------------------------------------+ | -| | | Intermediary: Send (auto-instr) | | -| |Link +------------------------------------+ | -| | | -| | | -| | | -| | Trace 2 | -| | | -| | +---------------------------------------+ | -| | | Consumer: Receive (auto-instr) | | -| | +---------------------------------------+ | -| | +-------------------------------------+ | -| +------ | Consumer: Process | | -| +-------------------------------------+ | -| | -+-------------------------------------------------------+ -``` - ## Conventions -To achieve the trace above, it is necessary to capture the context of -the event creation so that when the CloudEvent reaches its destination(s), this -context can be continued. Each CloudEvent acts then as the medium of this -context propagation. - -This document relies on the CloudEvents specification, which defines this -context propagation mechanism via the -[CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/extensions/distributed-tracing.md). -Once the trace context is set on the event -via the Distributed Tracing Extension, it MUST not be modified. - -The remainder of this section describes the semantic conventions for Spans -required to achieve the proposed trace. - -### Spans +CloudEvent-specific instrumentations SHOULD follow the span structure described in +the [Semantic Conventions for Messaging Spans](../messaging/messaging-spans.md). -#### Creation - -Instrumentation SHOULD create a new span and populate the +If CloudEvents are instrumented independently of the above conventions, +instrumentations can rely on the [CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/extensions/distributed-tracing.md) -on the event. This applies when: - -- A CloudEvent is created by the instrumented library. - It may be impossible or impractical to create the Span during event - creation (e.g. inside the constructor or in a factory method), - so instrumentation MAY create the Span later, when passing the event to the transport layer. -- A CloudEvent is created outside of the instrumented library - (e.g. directly constructed by the application owner, without calling a constructor or factory method), - and passed without the Distributed Tracing Extension populated. - -In case a CloudEvent is passed to the instrumented library with the -Distributed Tracing Extension already populated, instrumentation MUST NOT create -a span and MUST NOT modify the Distributed Tracing Extension on the event. - -- Span name: `CloudEvents Create ` - -- Span kind: PRODUCER - -- Span attributes: Instrumentation MUST add the required attributes defined - in the [table below](#attributes). - -#### Processing - -When an instrumented library supports processing of a single CloudEvent, -instrumentation SHOULD create a new span to trace it. - -Instrumentation SHOULD set the remote trace context from the -Distributed Tracing Extension as a link on the processing span. -Instrumentation MAY add attributes to the link to further describe it. - -- Span name: `CloudEvents Process ` - -- Span kind: CONSUMER - -- Span attributes: Instrumentation MUST add the required attributes defined - in the [table below](#attributes). +as means to propagate the trace context. -### Attributes +## Span attributes -The following attributes are applicable to creation and processing Spans. +Additionally, instrumentations may record the following CloudEvent-specific +attributes on spans created from the conventions described above. diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index fec15f7cf0..be65ba773e 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -6,11 +6,9 @@ linkTitle: Cassandra **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) 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. +The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend and override the [Database Semantic Conventions](database-spans.md). -`db.system` MUST be set to `"cassandra"`. +`db.system` MUST be set to `"cassandra"` and SHOULD be provided **at span creation time**. ## Attributes @@ -75,6 +73,16 @@ If a parameter has no name and instead is referenced only by index, then `` +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`db.query.text`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `db.cassandra.consistency_level` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 6fa48db887..593d42fb42 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -7,13 +7,11 @@ linkTitle: Cosmos DB **Status**: [Experimental][DocumentStatus] The Semantic Conventions for [Microsoft Cosmos DB](https://azure.microsoft.com/products/cosmos-db/) -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. +extend and override the [Database Semantic Conventions](database-spans.md). ## Attributes -`db.system` MUST be set to `"cosmosdb"`. +`db.system` MUST be set to `"cosmosdb"` and SHOULD be provided **at span creation time**. 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. @@ -76,6 +74,16 @@ If a parameter has no name and instead is referenced only by index, then `` +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`db.query.text`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `db.cosmosdb.connection_mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index 3aa0ad625c..f72458104b 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -6,11 +6,9 @@ linkTitle: CouchDB **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) 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. +The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and override the [Database Semantic Conventions](database-spans.md). -`db.system` MUST be set to `"couchdb"`. +`db.system` MUST be set to `"couchdb"` and SHOULD be provided **at span creation time**. ## Attributes @@ -43,6 +41,14 @@ described on this page. +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 88093233d8..c9f164ab49 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -142,6 +142,17 @@ If a parameter has no name and instead is referenced only by index, then `` +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`db.query.text`](/docs/attributes-registry/db.md) +* [`db.system`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | @@ -239,6 +250,10 @@ in which case the instrumentation MAY choose a different placeholder. Placeholders in a parameterized query SHOULD not be sanitized. E.g. `where id = $1` can be captured as is. +[IN-clauses](https://en.wikipedia.org/wiki/Where_(SQL)#IN) MAY be collapsed during sanitization, +e.g. from `IN (?, ?, ?, ?)` to `IN (?)`, as this can help with extremely long IN-clauses, +and can help control cardinality for users who choose to (optionally) add `db.query.text` to their metric attributes. + ## Semantic Conventions for specific database technologies More specific Semantic Conventions are defined for the following database technologies: diff --git a/docs/database/dynamodb.md b/docs/database/dynamodb.md index eb342339f0..bb83447e94 100644 --- a/docs/database/dynamodb.md +++ b/docs/database/dynamodb.md @@ -7,94 +7,13 @@ linkTitle: AWS DynamoDB **Status**: [Experimental][DocumentStatus] The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) extend and override the general -[AWS SDK Semantic Conventions](/docs/cloud-providers/aws-sdk.md) -that describe common AWS SDK attributes and the [Database Semantic Conventions](database-spans.md). -that describe common database operations attributes in addition to the Semantic Conventions -described on this page. +[AWS SDK Semantic Conventions](/docs/cloud-providers/aws-sdk.md) and [Database Semantic Conventions](database-spans.md). -## Common Attributes - -These attributes are filled in for all DynamoDB request types. - - - - - - - - -| 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`. [1] | `dynamodb` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge. - - - -`db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -|---|---|---| -| `adabas` | Adabas (Adaptable Database System) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cassandra` | Apache Cassandra | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `clickhouse` | ClickHouse | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cockroachdb` | CockroachDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cosmosdb` | Microsoft Azure Cosmos DB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `couchbase` | Couchbase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `couchdb` | CouchDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db2` | IBM Db2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `derby` | Apache Derby | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `dynamodb` | Amazon DynamoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `edb` | EnterpriseDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `elasticsearch` | Elasticsearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `filemaker` | FileMaker | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `firebird` | Firebird | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `geode` | Apache Geode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `h2` | H2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `hanadb` | SAP HANA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `hbase` | Apache HBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `hive` | Apache Hive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `hsqldb` | HyperSQL DataBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `influxdb` | InfluxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `informix` | Informix | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `ingres` | Ingres | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `instantdb` | InstantDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `interbase` | InterBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `intersystems_cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mariadb` | MariaDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `maxdb` | SAP MaxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mssql` | Microsoft SQL Server | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mysql` | MySQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `netezza` | Netezza | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `opensearch` | OpenSearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `oracle` | Oracle Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `other_sql` | Some other SQL database. Fallback only. See notes. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `pervasive` | Pervasive PSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `pointbase` | PointBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `postgresql` | PostgreSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `progress` | Progress Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `redis` | Redis | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `redshift` | Amazon Redshift | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `spanner` | Cloud Spanner | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `sqlite` | SQLite | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `sybase` | Sybase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `teradata` | Teradata | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `trino` | Trino | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `vertica` | Vertica | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - - - - - - - +`db.system` MUST be set to `"dynamodb"` and SHOULD be provided **at span creation time**. ## DynamoDB.BatchGetItem - + @@ -135,7 +54,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.BatchWriteItem - + @@ -177,7 +96,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.CreateTable - + @@ -223,7 +142,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.DeleteItem - + @@ -265,7 +184,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.DeleteTable - + @@ -305,7 +224,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.DescribeTable - + @@ -345,7 +264,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.GetItem - + @@ -388,7 +307,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.ListTables - + @@ -430,7 +349,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.PutItem - + @@ -472,7 +391,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.Query - + @@ -520,7 +439,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.Scan - + @@ -571,7 +490,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.UpdateItem - + @@ -613,7 +532,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.UpdateTable - + diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index d881f79ace..8ebadbaa4d 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -6,11 +6,9 @@ linkTitle: Elasticsearch **Status**: [Experimental][DocumentStatus] -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. +The Semantic Conventions for [Elasticsearch](https://www.elastic.co/) extend and override the [Database Semantic Conventions](database-spans.md). -`db.system` MUST be set to `"elasticsearch"`. +`db.system` MUST be set to `"elasticsearch"` and SHOULD be provided **at span creation time**. ## Span Name @@ -84,6 +82,18 @@ Even though parameterized query text can potentially have sensitive data, by usi +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`db.query.text`](/docs/attributes-registry/db.md) +* [`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) + `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/hbase.md b/docs/database/hbase.md index 24573caae9..1fc8c19d91 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -6,11 +6,9 @@ linkTitle: HBase **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [HBase](https://hbase.apache.org/) 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. +The Semantic Conventions for [HBase](https://hbase.apache.org/) extend and override the [Database Semantic Conventions](database-spans.md). -`db.system` MUST be set to `"hbase"`. +`db.system` MUST be set to `"hbase"` and SHOULD be provided **at span creation time**. ## Attributes @@ -50,6 +48,15 @@ For batch operations, if the individual operations are known to have the same op +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index 50ff165787..ff514fc0fe 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -6,11 +6,9 @@ linkTitle: MongoDB **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [MongoDB](https://www.mongodb.com/) 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. +The Semantic Conventions for [MongoDB](https://www.mongodb.com/) extend and override the [Database Semantic Conventions](database-spans.md). -`db.system` MUST be set to `"mongodb"`. +`db.system` MUST be set to `"mongodb"` and SHOULD be provided **at span creation time**. ## Attributes @@ -48,6 +46,15 @@ For batch operations, if the individual operations are known to have the same co +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 6962223af7..50460220d2 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -6,11 +6,9 @@ linkTitle: MSSQL **Status**: [Experimental][DocumentStatus] -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. +The Semantic Conventions for the *Microsoft SQL Server* extend and override the [Database Semantic Conventions](database-spans.md). -`db.system` MUST be set to `"mssql"`. +`db.system` MUST be set to `"mssql"` and SHOULD be provided **at span creation time**. ## Attributes @@ -65,6 +63,16 @@ If a parameter has no name and instead is referenced only by index, then `` +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`db.query.text`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/redis.md b/docs/database/redis.md index bbe41a21c2..501a239ed5 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -6,11 +6,9 @@ linkTitle: Redis **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [Redis](https://redis.com/) 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. +The Semantic Conventions for [Redis](https://redis.com/) extend and override the [Database Semantic Conventions](database-spans.md). -`db.system` MUST be set to `"redis"`. +`db.system` MUST be set to `"redis"` and SHOULD be provided **at span creation time**. ## Attributes @@ -23,7 +21,7 @@ described on this page. | 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.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) (captured as a string). [1] | `0`; `1`; `15` | `Conditionally Required` If and only if it can be captured reliably. | ![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. [2] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [3] | ![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. [4] | `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. [5] | `80`; `8080`; `443` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -63,6 +61,15 @@ If a parameter has no name and instead is referenced only by index, then `` +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`db.query.text`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/sql.md b/docs/database/sql.md index 524c5878bd..7a2b57f3e0 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -104,6 +104,15 @@ If a parameter has no name and instead is referenced only by index, then `` +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`db.query.text`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 98860c6a05..56d2696acb 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -86,6 +86,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -182,6 +183,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -258,6 +260,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -333,6 +336,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -414,6 +418,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -491,6 +496,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -581,6 +587,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -656,6 +663,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 4ed35e73f9..b36fde656a 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -168,7 +168,7 @@ For every message in the event, the [message system attributes][] (not message a 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.33.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. +See [compatibility](../non-normative/compatibility/aws.md#context-propagation) for more info. - [`faas.trigger`][faas] MUST be set to `pubsub`. - [`messaging.operation.type`](/docs/messaging/messaging-spans.md) MUST be set to `process`. @@ -181,7 +181,7 @@ corresponding to the SQS event. The [message system attributes][] (not message a 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.33.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. +See [compatibility](../non-normative/compatibility/aws.md#context-propagation) for more info. - [`faas.trigger`][faas] MUST be set to `pubsub`. - [`messaging.operation.type`](/docs/messaging/messaging-spans.md#messaging-attributes) MUST be set to `process`. diff --git a/docs/gen-ai/gen-ai-metrics.md b/docs/gen-ai/gen-ai-metrics.md index 9f8e165cff..b2db3e1b2a 100644 --- a/docs/gen-ai/gen-ai-metrics.md +++ b/docs/gen-ai/gen-ai-metrics.md @@ -71,21 +71,38 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of [1, 4, 16, 64 | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. | `chat`; `completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.token.type`](/docs/attributes-registry/gen-ai.md) | string | The type of token being counted. | `input`; `output` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [3] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. -For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. +**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. -**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + + + +`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. @@ -144,24 +161,33 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of [ 0.01, 0.02, | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. | `chat`; `completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [4] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. + +**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. -**[1]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. -For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. -**[2]:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, +**[3]:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[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.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. @@ -172,6 +198,14 @@ Instrumentations SHOULD document the list of errors they report. | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + `gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | @@ -227,24 +261,33 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. | `chat`; `completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [4] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. + +**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. -**[1]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. -For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. -**[2]:** The `error.type` SHOULD match the error code returned by the Generative AI service, +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +**[3]:** The `error.type` SHOULD match the error code returned by the Generative AI service, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[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.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. @@ -255,6 +298,14 @@ Instrumentations SHOULD document the list of errors they report. | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + `gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | @@ -310,20 +361,37 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. | `chat`; `completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [3] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. -For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. +**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. -**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + + + +`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. @@ -380,20 +448,37 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. | `chat`; `completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [3] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. + +**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. -**[1]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. -For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[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]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md index d2fb54b987..505935dee1 100644 --- a/docs/gen-ai/gen-ai-spans.md +++ b/docs/gen-ai/gen-ai-spans.md @@ -10,6 +10,7 @@ linkTitle: Generative AI traces +- [Name](#name) - [Configuration](#configuration) - [GenAI attributes](#genai-attributes) - [Events](#events) @@ -20,8 +21,11 @@ A request to an Generative AI 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 Generative AI system. -For example, the API name such as [Create chat completion](https://platform.openai.com/docs/api-reference/chat/create) could be represented as `completion gpt-4` to include the API and the model name. +## Name + +GenAI spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/trace/api.md#span). +The **span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`. +Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format. ## Configuration @@ -45,8 +49,11 @@ These attributes track input data and metadata for a request to an GenAI model. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [1] | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [2] | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [3] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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 the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [5] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.presence_penalty`](/docs/attributes-registry/gen-ai.md) | double | The presence penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -56,17 +63,50 @@ These attributes track input data and metadata for a request to an GenAI model. | [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the GenAI request. | `1.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.response.finish_reasons`](/docs/attributes-registry/gen-ai.md) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [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 GenAI 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 GenAI input or prompt. | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [6] | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI input (prompt). | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI response (completion). | `180` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. + +**[2]:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + +**[3]:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +**[4]:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, +the canonical name of exception that occurred, or another low-cardinality error identifier. +Instrumentations SHOULD document the list of errors they report. + +**[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 available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. -**[1]:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. +**[7]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[2]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. -For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. -**[3]:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. +`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. diff --git a/docs/general/attributes.md b/docs/general/attributes.md index f8da8d3a6c..cb3f3360ca 100644 --- a/docs/general/attributes.md +++ b/docs/general/attributes.md @@ -1,6 +1,6 @@ # General Attributes @@ -245,6 +245,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/general/events.md b/docs/general/events.md index 63fbe0812f..87460baae5 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -1,6 +1,6 @@ # Semantic Conventions for Events @@ -21,9 +21,9 @@ the conventions included here, and Events 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_ (data) of any type permitted +In addition to a required name, an Event may contain a _payload_ (body) 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_ (data) will constitute the `Body` of the `LogRecord`. +In its implementation, the Event _payload_ (body) will constitute the `Body` of the `LogRecord`. Like all other OpenTelemetry signals, an Event has optional attribute metadata that helps describe the event context. @@ -60,19 +60,19 @@ structure and semantics will also be defined. * An event MUST have an `event.name` attribute that uniquely identifies the event. * It MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/common#attribute) attributes that provide additional context about the event. -* It MAY contain a _payload_ (data) that describes the specific details of the +* It MAY contain a _payload_ (body) that describes the specific details of the named event. -* The event name uniquely identifies event structure / type of the _payload_ (data) +* The event name uniquely identifies event structure / type of the _payload_ (body) and the set of attributes. -* The _payload_ (data) MAY contain any type supported by the OpenTelemetry data +* The _payload_ (body) MAY contain any type supported by the OpenTelemetry data model for the log [body](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-body) and the semantic conventions will define the expected structure of the _payload_ - (data) for the event. -* The _payload_ (data) SHOULD be used to represent the structure of the event. + (body) for the event. +* The _payload_ (body) SHOULD be used to represent the structure of the event. Recommendations for defining events: -* Use the _payload_ (data) to represent the details of the event instead of a +* Use the _payload_ (body) to represent the details of the event instead of a collection of [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/common#attribute) attributes. * Events SHOULD be generated / produced / recorded using the @@ -81,12 +81,18 @@ Recommendations for defining events: * The Event API is not yet available in all OpenTelemetry SDKs. * TODO: Add deep link to the [compliance matrix of the Event API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md) when it exists. -* It's NOT RECOMMENDED to prefix the _payload_ (data) _fields_ with the `event.name` to +* It's NOT RECOMMENDED to prefix the _payload_ (body) _fields_ with the `event.name` to avoid redundancy and to keep the event definition clean. * The events SHOULD document their semantic conventions including event name, attributes, and the payload. -### Event payload (data) +Recommendations on using attributes vs. body fields: + +* If the field should be comparable across every type of record, it should be an attribute. +* If the field is specific to the event itself, then it should be a body field. +* Unless the same `event.name` exists on two events, anything in two event bodies is not comparable to each other. + +### Event payload (body) * Common attribute naming conventions and [registry](../attributes-registry/README.md) requirements don't apply to event payload fields. diff --git a/docs/general/logs.md b/docs/general/logs.md index 499b719841..24ead6f931 100644 --- a/docs/general/logs.md +++ b/docs/general/logs.md @@ -1,6 +1,6 @@ # General Logs Attributes @@ -44,9 +44,12 @@ These attributes may be used for identifying a Log Record. | 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) | +| [`log.record.original`](/docs/attributes-registry/log.md) | string | The complete orignal Log Record. [1] | `77 <86>1 2015-08-06T21:58:59.694Z 192.168.2.133 inactive - - - Something happened`; `[INFO] 8/3/24 12:34:56 Something happened` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`log.record.uid`](/docs/attributes-registry/log.md) | string | A unique identifier for the Log Record. [2] | `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. +**[1]:** This value MAY be added when processing a Log Record which was originally transmitted as a string or equivalent data type AND the Body field of the Log Record does not contain the same value. (e.g. a syslog or a log record read from a file.) + +**[2]:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values. The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), but other identifiers (e.g. UUID) may be used as needed. diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 09892e5fc0..3c9740a478 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -1,6 +1,6 @@ # Metrics Semantic Conventions diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 180d595d41..c931045c94 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -93,19 +93,31 @@ Instrumentation MUST NOT default to using URI path as a `{target}`. the response body; or 3xx codes with max redirects exceeded), in which case status MUST be set to `Error`. +> **Note:** +> +> The classification of an HTTP status code as an error depends on the context. +> For example, a 404 "Not Found" status code indicates an error if the application +> expected the resource to be available. However, it is not an error when the +> application is simply checking whether the resource exists. +> +> Instrumentations that have additional context about a specific request MAY use +> this context to set the span status more precisely. +> Instrumentations that don't have any additional context MUST follow the +> guidelines in this section. + For HTTP status codes in the 4xx range span status MUST be left unset in case of `SpanKind.SERVER` -and MUST be set to `Error` in case of `SpanKind.CLIENT`. +and SHOULD be set to `Error` in case of `SpanKind.CLIENT`. For HTTP status codes in the 5xx range, as well as any other code the client -failed to interpret, span status MUST be set to `Error`. +failed to interpret, span status SHOULD be set to `Error`. Don't set the span status description if the reason can be inferred from `http.response.status_code`. HTTP request may fail if it was cancelled or an error occurred preventing the client or server from sending/receiving the request/response fully. -When instrumentation detects such errors it MUST set span status to `Error` -and MUST set the `error.type` attribute. +When instrumentation detects such errors it SHOULD set span status to `Error` +and SHOULD set the `error.type` attribute. ## HTTP client @@ -246,6 +258,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -510,6 +523,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md index 0d2d6e4e7d..72ef2814e2 100644 --- a/docs/messaging/azure-messaging.md +++ b/docs/messaging/azure-messaging.md @@ -6,7 +6,7 @@ linkTitle: Azure Messaging **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. +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). ## Azure Service Bus diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md index 1957e3dbbc..c9286a02b6 100644 --- a/docs/messaging/gcp-pubsub.md +++ b/docs/messaging/gcp-pubsub.md @@ -6,7 +6,7 @@ linkTitle: 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. +The Semantic Conventions for [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) extend and override the [Messaging Semantic Conventions](README.md). `messaging.system` MUST be set to `"gcp_pubsub"` and SHOULD be provided **at span creation time**. diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index 14b01a072d..2964be5d02 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -14,9 +14,7 @@ linkTitle: Kafka -The Semantic Conventions for [Apache Kafka](https://kafka.apache.org/) 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. +The Semantic Conventions for [Apache Kafka](https://kafka.apache.org/) extend and override the [Messaging Semantic Conventions](README.md). `messaging.system` MUST be set to `"kafka"` and SHOULD be provided **at span creation time**. @@ -44,7 +42,7 @@ For Apache Kafka, the following additional attributes are defined: | [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) | string | Kafka [consumer group id](https://docs.confluent.io/platform/current/clients/consumer.html). | `my-group`; `indexer` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | String representation of the partition id the message (or batch) is sent to or received from. | `1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.kafka.message.key`](/docs/attributes-registry/messaging.md) | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [9] | `myKey` | `Recommended` If span describes operation on a single message. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.kafka.message.offset`](/docs/attributes-registry/messaging.md) | int | The offset of a record in the corresponding Kafka partition. | `42` | `Recommended` If span describes operation on a single message. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.kafka.offset`](/docs/attributes-registry/messaging.md) | int | The offset of a record in the corresponding Kafka partition. | `42` | `Recommended` If span describes operation on a single message. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. [10] | `1439` | `Recommended` If span describes operation on a single message. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.id`](/docs/attributes-registry/messaging.md) | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | `Recommended` If span describes operation on a single message. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [11] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 0855774bcf..d2d00ae79e 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -26,7 +26,6 @@ - [Producer spans](#producer-spans) - [Consumer spans](#consumer-spans) - [Messaging attributes](#messaging-attributes) - - [Consumer attributes](#consumer-attributes) - [Recording per-message attributes on batch operations](#recording-per-message-attributes-on-batch-operations) - [Examples](#examples) - [Topic with multiple consumers](#topic-with-multiple-consumers) @@ -89,12 +88,6 @@ 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 @@ -288,9 +281,8 @@ Messaging attributes are organized into the following namespaces: - `messaging.message`: Contains attributes that describe individual messages. - `messaging.destination`: Contains attributes that describe the logical entity messages are published to. See [Destinations](#destinations) for more details. -- `messaging.destination_publish`: Contains attributes that describe the logical entity messages were originally published to. See [Destinations](#destinations) for more details. - `messaging.batch`: Contains attributes that describe batch operations. -- `messaging.consumer`: Contains [consumer attributes](#consumer-attributes) that describe the application instance that consumes a message. See [consumer](#consumer) for more details. +- `messaging.consumer`: Contains 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. @@ -436,45 +428,6 @@ and SHOULD be provided **at span creation time** (if provided at all): - - - - - -### Consumer attributes - -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. - - - -The following attributes can be important for making sampling decisions -and SHOULD be provided **at span creation time** (if provided at all): - -* [`messaging.destination_publish.name`](/docs/attributes-registry/messaging.md) - - diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md index bd4a1ed73d..3648280e3e 100644 --- a/docs/messaging/rabbitmq.md +++ b/docs/messaging/rabbitmq.md @@ -6,9 +6,7 @@ linkTitle: RabbitMQ **Status**: [Experimental][DocumentStatus] -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. +The Semantic Conventions for [RabbitMQ](https://www.rabbitmq.com/) extend and override the [Messaging Semantic Conventions](README.md). `messaging.system` MUST be set to `"rabbitmq"` and SHOULD be provided **at span creation time**. diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md index a602244433..6317f0cc3c 100644 --- a/docs/messaging/rocketmq.md +++ b/docs/messaging/rocketmq.md @@ -6,9 +6,7 @@ linkTitle: RocketMQ **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [Apache RocketMQ](https://rocketmq.apache.org/) 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. +The Semantic Conventions for [Apache RocketMQ](https://rocketmq.apache.org/) extend and override the [Messaging Semantic Conventions](README.md). `messaging.system` MUST be set to `"rocketmq"` and SHOULD be provided **at span creation time**. diff --git a/docs/non-normative/README.md b/docs/non-normative/README.md new file mode 100644 index 0000000000..c51419111d --- /dev/null +++ b/docs/non-normative/README.md @@ -0,0 +1,11 @@ + + +# Non-normative supplementary information + +The pages in this section are **non-normative**, most are supplementary +guidelines. diff --git a/docs/non-normative/compatibility/README.md b/docs/non-normative/compatibility/README.md new file mode 100644 index 0000000000..fa1af86c8e --- /dev/null +++ b/docs/non-normative/compatibility/README.md @@ -0,0 +1,7 @@ + + +# Compatibility diff --git a/supplementary-guidelines/compatibility/aws.md b/docs/non-normative/compatibility/aws.md similarity index 93% rename from supplementary-guidelines/compatibility/aws.md rename to docs/non-normative/compatibility/aws.md index 3777cb22a9..e40a7cc1aa 100644 --- a/supplementary-guidelines/compatibility/aws.md +++ b/docs/non-normative/compatibility/aws.md @@ -1,6 +1,10 @@ + + # Compatibility Considerations for AWS -This document highlights compatibility considerations for OpenTelemetry +This page highlights compatibility considerations for OpenTelemetry instrumentations when interacting with AWS managed services using an aws-sdk, a third-party library, or a direct HTTP request. diff --git a/docs/http/migration-guide.md b/docs/non-normative/http-migration.md similarity index 98% rename from docs/http/migration-guide.md rename to docs/non-normative/http-migration.md index 65fea1a3fe..d0c70fe68f 100644 --- a/docs/http/migration-guide.md +++ b/docs/non-normative/http-migration.md @@ -1,4 +1,9 @@ -# HTTP semantic convention stability migration guide + + +# HTTP semantic convention stability migration Due to the significant number of modifications and the extensive user base affected by them, existing HTTP instrumentations published by @@ -207,7 +212,7 @@ which case `{summary}` is `HTTP`. ### Migrating from `<= v1.16.0` -This document does not cover these versions. +This page 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 diff --git a/supplementary-guidelines/semantic_conventions_code_generation.md b/docs/non-normative/libraries.md similarity index 93% rename from supplementary-guidelines/semantic_conventions_code_generation.md rename to docs/non-normative/libraries.md index 76436fed77..320627ed3e 100644 --- a/supplementary-guidelines/semantic_conventions_code_generation.md +++ b/docs/non-normative/libraries.md @@ -1,3 +1,8 @@ + + # Semantic convention libraries @@ -115,4 +120,4 @@ Code-generation usually involves several steps which could be semi-automated: 5. Fix lint violations in the auto-generated code (if any) 6. Send the PR with new code to the corresponding repository -Here're the examples of how steps 2-5 are implemented for [Java](https://github.com/open-telemetry/semantic-conventions-java/blob/7da24068eea69dff11a78d59750b115dc4c5854d/build.gradle.kts#L55-L137) and [Python](https://github.com/open-telemetry/opentelemetry-python/blob/397e357dfad3e6ff42c09c74d5945dfdcad24bdd/scripts/semconv/generate.sh). +Here are examples of how steps 2-5 are implemented for [Java](https://github.com/open-telemetry/semantic-conventions-java/blob/7da24068eea69dff11a78d59750b115dc4c5854d/build.gradle.kts#L55-L137) and [Python](https://github.com/open-telemetry/opentelemetry-python/blob/397e357dfad3e6ff42c09c74d5945dfdcad24bdd/scripts/semconv/generate.sh). diff --git a/docs/resource/deployment-environment.md b/docs/resource/deployment-environment.md index 091ad8dba5..72cb250024 100644 --- a/docs/resource/deployment-environment.md +++ b/docs/resource/deployment-environment.md @@ -15,15 +15,15 @@ | 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) | +| [`deployment.environment.name`](/docs/attributes-registry/deployment.md) | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** `deployment.environment` does not affect the uniqueness constraints defined through +**[1]:** `deployment.environment.name` does not affect the uniqueness constraints defined through the `service.namespace`, `service.name` and `service.instance.id` resource attributes. This implies that resources carrying the following attribute combinations MUST be considered to be identifying the same service: -* `service.name=frontend`, `deployment.environment=production` -* `service.name=frontend`, `deployment.environment=staging`. +* `service.name=frontend`, `deployment.environment.name=production` +* `service.name=frontend`, `deployment.environment.name=staging`. diff --git a/docs/resource/process.md b/docs/resource/process.md index a081022d6f..ff17dfcfbf 100644 --- a/docs/resource/process.md +++ b/docs/resource/process.md @@ -91,7 +91,7 @@ On Windows and other systems where the native format of process commands is a si | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`process.runtime.description`](/docs/attributes-registry/process.md) | string | An additional description about the runtime of the process, for example a specific vendor customization of the runtime environment. | `Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`process.runtime.name`](/docs/attributes-registry/process.md) | string | The name of the runtime of this process. For compiled native binaries, this SHOULD be the name of the compiler. | `OpenJDK Runtime Environment` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.runtime.name`](/docs/attributes-registry/process.md) | string | The name of the runtime of this process. | `OpenJDK Runtime Environment` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`process.runtime.version`](/docs/attributes-registry/process.md) | string | The version of the runtime of this process, as returned by the runtime without modification. | `14.0.2` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index f8c83543e2..1642389989 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -386,6 +386,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 610d7c85d6..0595583160 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -138,6 +138,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -220,6 +221,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/runtime/README.md b/docs/runtime/README.md index 0d0dd6033f..7f17940f36 100644 --- a/docs/runtime/README.md +++ b/docs/runtime/README.md @@ -50,6 +50,7 @@ semantic conventions when instrumenting runtime environments. - [Go](go-metrics.md) - [JVM](jvm-metrics.md) - [Node.js](nodejs-metrics.md) +- [V8 JS Engine](v8js-metrics.md) ### Attributes diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md index 33bfa93f4c..cbda57ad10 100644 --- a/docs/runtime/jvm-metrics.md +++ b/docs/runtime/jvm-metrics.md @@ -33,7 +33,7 @@ This document describes semantic conventions for JVM metrics in OpenTelemetry. - [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.used`](#metric-jvmbuffermemoryused) - [Metric: `jvm.buffer.memory.limit`](#metric-jvmbuffermemorylimit) - [Metric: `jvm.buffer.count`](#metric-jvmbuffercount) @@ -743,12 +743,12 @@ This metric is obtained from [`OperatingSystemMXBean#getSystemLoadAverage()`](ht -### Metric: `jvm.buffer.memory.usage` +### Metric: `jvm.buffer.memory.used` 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--). - + @@ -757,7 +757,7 @@ This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.o | 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) | +| `jvm.buffer.memory.used` | UpDownCounter | `By` | Measure of memory used by buffers. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -765,7 +765,7 @@ This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.o - + diff --git a/docs/runtime/v8js-metrics.md b/docs/runtime/v8js-metrics.md new file mode 100644 index 0000000000..d8b4e07a65 --- /dev/null +++ b/docs/runtime/v8js-metrics.md @@ -0,0 +1,315 @@ + + +# Semantic Conventions for V8 JS Engine Runtime Metrics + +**Status**: [Experimental][DocumentStatus] + +This document describes semantic conventions for V8 JS Engine Runtime metrics in OpenTelemetry. This engine is used in some javascript runtime such as Node.js and Deno. + + + + + +- [Experimental](#experimental) + - [Metric: `v8js.gc.duration`](#metric-v8jsgcduration) + - [Metric: `v8js.memory.heap.limit`](#metric-v8jsmemoryheaplimit) + - [Metric: `v8js.memory.heap.used`](#metric-v8jsmemoryheapused) + - [Metric: `v8js.heap.space.available_size`](#metric-v8jsheapspaceavailable_size) + - [Metric: `v8js.heap.space.physical_size`](#metric-v8jsheapspacephysical_size) + + + +## Experimental + +**Status**: [Experimental][DocumentStatus] + +**Description:** Experimental V8 JS Engine Runtime metrics captured under `v8js`. + +### Metric: `v8js.gc.duration` + +This metric is [recommended][MetricRecommended]. + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/metrics/api.md#instrument-advisory-parameters) +of `[ 0.01, 0.1, 1, 10 ]`. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `v8js.gc.duration` | Histogram | `s` | Garbage collection duration. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** The values can be retrieve from [`perf_hooks.PerformanceObserver(...).observe({ entryTypes: ['gc'] })`](https://nodejs.org/api/perf_hooks.html#performanceobserverobserveoptions) + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`v8js.gc.type`](/docs/attributes-registry/v8js.md) | string | The type of garbage collection. | `major`; `minor`; `incremental` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`v8js.gc.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `incremental` | Incremental (Incremental Marking). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `major` | Major (Mark Sweep Compact). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `minor` | Minor (Scavenge). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `weakcb` | Weak Callbacks (Process Weak Callbacks). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `v8js.memory.heap.limit` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `v8js.memory.heap.limit` | UpDownCounter | `By` | Total heap memory size pre-allocated. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** The value can be retrieved from value `space_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`v8js.heap.space.name`](/docs/attributes-registry/v8js.md) | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + +`v8js.heap.space.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `code_space` | Code memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `v8js.memory.heap.used` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `v8js.memory.heap.used` | UpDownCounter | `By` | Heap Memory size allocated. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** The value can be retrieved from value `space_used_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`v8js.heap.space.name`](/docs/attributes-registry/v8js.md) | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + +`v8js.heap.space.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `code_space` | Code memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `v8js.heap.space.available_size` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `v8js.heap.space.available_size` | UpDownCounter | `By` | Heap space available size. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `space_available_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`v8js.heap.space.name`](/docs/attributes-registry/v8js.md) | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + +`v8js.heap.space.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `code_space` | Code memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `v8js.heap.space.physical_size` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `v8js.heap.space.physical_size` | UpDownCounter | `By` | Committed size of a heap space. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `physical_space_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`v8js.heap.space.name`](/docs/attributes-registry/v8js.md) | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + +`v8js.heap.space.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `code_space` | Code memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index cd01009e28..46ef36db2f 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -57,6 +57,7 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam - [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: `system.linux.memory.slab.usage`](#metric-systemlinuxmemoryslabusage) @@ -1305,6 +1306,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -1474,6 +1476,58 @@ See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5 + + + + + +### Metric: `system.linux.memory.slab.usage` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.linux.memory.slab.usage` | UpDownCounter | `By` | Reports the memory used by the Linux kernel for managing caches of frequently used objects. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** The sum over the `reclaimable` and `unreclaimable` state values in `linux.memory.slab.usage` SHOULD be equal to the total slab memory available on the system. +Note that the total slab memory is not constant and may vary over time. +See also the [Slab allocator](https://blogs.oracle.com/linux/post/understanding-linux-kernel-memory-statistics) and `Slab` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html). + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`linux.memory.slab.state`](/docs/attributes-registry/linux.md) | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`linux.memory.slab.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `reclaimable` | reclaimable | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unreclaimable` | unreclaimable | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + diff --git a/internal/tools/schema_check.sh b/internal/tools/schema_check.sh index 68883941b1..779fd957e8 100755 --- a/internal/tools/schema_check.sh +++ b/internal/tools/schema_check.sh @@ -6,7 +6,7 @@ set -e -BUILD_TOOL_SCHEMAS_VERSION=0.24.0 +BUILD_TOOL_SCHEMAS_VERSION=0.25.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") diff --git a/internal/tools/scripts/update-issue-template-areas.sh b/internal/tools/scripts/update-issue-template-areas.sh index da2f81ebcf..e905808a18 100755 --- a/internal/tools/scripts/update-issue-template-areas.sh +++ b/internal/tools/scripts/update-issue-template-areas.sh @@ -11,6 +11,14 @@ set -euo pipefail +OS=$(uname | tr '[:upper:]' '[:lower:]') + +if [[ "${OS}" == "darwin" ]]; then + SED="gsed" +else + SED="sed" +fi + CUR_DIRECTORY=$(dirname "$0") REPO_DIR="$( cd "$CUR_DIRECTORY/../../../" && pwd )" GITHUB_DIR="$( cd "$REPO_DIR/.github/" && pwd )" @@ -37,7 +45,7 @@ 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" +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/update_specification_version.sh b/internal/tools/update_specification_version.sh index 34af42f446..c5a8387f1a 100755 --- a/internal/tools/update_specification_version.sh +++ b/internal/tools/update_specification_version.sh @@ -27,7 +27,7 @@ fix_file() { "$1" } -important_files=("docs" "model" "README.md" "supplementary-guidelines") +important_files=("docs" "model" "README.md") # TODO - limit to markdown/yaml files? find "${important_files[@]}" -type f -not -path '*/.*' -print0 | while read -d $'\0' file; do diff --git a/model/README.md b/model/README.md index 012b4f4ed7..ec76e3f883 100644 --- a/model/README.md +++ b/model/README.md @@ -14,12 +14,12 @@ Semantic conventions for the spec MUST adhere to the [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.24.0/semantic-conventions/syntax.md) +Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.25.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.24.0/semantic-conventions/README.md) for what extension you need. +[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.25.0/semantic-conventions/README.md) for what extension you need. ## Generating markdown diff --git a/model/logs/general.yaml b/model/logs/general.yaml index b4afe2c16c..d4835d6982 100644 --- a/model/logs/general.yaml +++ b/model/logs/general.yaml @@ -6,3 +6,5 @@ groups: attributes: - ref: log.record.uid requirement_level: opt_in + - ref: log.record.original + requirement_level: opt_in diff --git a/model/metrics/deprecated/jvm-metrics.yaml b/model/metrics/deprecated/jvm-metrics.yaml new file mode 100644 index 0000000000..2641fc1a5c --- /dev/null +++ b/model/metrics/deprecated/jvm-metrics.yaml @@ -0,0 +1,10 @@ +groups: + - id: metric.jvm.buffer.memory.usage.deprecated + type: metric + metric_name: jvm.buffer.memory.usage + stability: experimental + deprecated: "Replaced by `jvm.buffer.memory.used`." + brief: "Deprecated, use `jvm.buffer.memory.used` instead." + extends: attributes.jvm.buffer + instrument: updowncounter + unit: "By" diff --git a/model/metrics/gen-ai.yaml b/model/metrics/gen-ai.yaml index 7c9979cf21..2c7035876c 100644 --- a/model/metrics/gen-ai.yaml +++ b/model/metrics/gen-ai.yaml @@ -4,10 +4,12 @@ groups: brief: 'This group describes GenAI metrics attributes' attributes: - ref: server.address + brief: GenAI server address. requirement_level: recommended - ref: server.port + brief: GenAI server port. requirement_level: - conditionally_required: If `sever.address` is set. + conditionally_required: If `server.address` is set. - ref: gen_ai.response.model requirement_level: recommended - ref: gen_ai.request.model diff --git a/model/metrics/jvm-metrics-experimental.yaml b/model/metrics/jvm-metrics-experimental.yaml index 6cb5f6fb2c..33b7a89c4b 100644 --- a/model/metrics/jvm-metrics-experimental.yaml +++ b/model/metrics/jvm-metrics-experimental.yaml @@ -42,9 +42,9 @@ groups: - ref: jvm.buffer.pool.name requirement_level: recommended - - id: metric.jvm.buffer.memory.usage + - id: metric.jvm.buffer.memory.used type: metric - metric_name: jvm.buffer.memory.usage + metric_name: jvm.buffer.memory.used stability: experimental extends: attributes.jvm.buffer brief: "Measure of memory used by buffers." diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml index 25e2d06665..9784deeece 100644 --- a/model/metrics/system-metrics.yaml +++ b/model/metrics/system-metrics.yaml @@ -342,3 +342,17 @@ groups: instrument: updowncounter unit: "By" attributes: [] + + - id: metric.system.linux.memory.slab.usage + type: metric + metric_name: system.linux.memory.slab.usage + stability: experimental + brief: "Reports the memory used by the Linux kernel for managing caches of frequently used objects." + note: | + The sum over the `reclaimable` and `unreclaimable` state values in `linux.memory.slab.usage` SHOULD be equal to the total slab memory available on the system. + Note that the total slab memory is not constant and may vary over time. + See also the [Slab allocator](https://blogs.oracle.com/linux/post/understanding-linux-kernel-memory-statistics) and `Slab` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html). + instrument: updowncounter + unit: "By" + attributes: + - ref: linux.memory.slab.state diff --git a/model/metrics/v8js-metrics.yaml b/model/metrics/v8js-metrics.yaml new file mode 100644 index 0000000000..be0a43b09a --- /dev/null +++ b/model/metrics/v8js-metrics.yaml @@ -0,0 +1,69 @@ +groups: + - id: metric.veightjs.gc.duration + type: metric + metric_name: v8js.gc.duration + brief: "Garbage collection duration." + instrument: histogram + unit: "s" + stability: experimental + prefix: v8js.gc + attributes: + - ref: v8js.gc.type + requirement_level: required + note: > + The values can be retrieve from [`perf_hooks.PerformanceObserver(...).observe({ entryTypes: ['gc'] })`](https://nodejs.org/api/perf_hooks.html#performanceobserverobserveoptions) + + - id: metric.veightjs.memory.heap.limit + type: metric + metric_name: v8js.memory.heap.limit + brief: "Total heap memory size pre-allocated." + instrument: updowncounter + unit: "By" + stability: experimental + attributes: + - ref: v8js.heap.space.name + requirement_level: required + note: > + The value can be retrieved from value `space_size` of + [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + - id: metric.veightjs.memory.heap.used + type: metric + metric_name: v8js.memory.heap.used + brief: "Heap Memory size allocated." + instrument: updowncounter + unit: "By" + stability: experimental + attributes: + - ref: v8js.heap.space.name + requirement_level: required + note: > + The value can be retrieved from value `space_used_size` of + [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + - id: metric.veightjs.heap.space.available_size + type: metric + metric_name: v8js.heap.space.available_size + brief: "Heap space available size." + instrument: updowncounter + unit: "By" + stability: experimental + attributes: + - ref: v8js.heap.space.name + requirement_level: required + note: > + Value can be retrieved from value `space_available_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + - id: metric.veightjs.heap.space.physical_size + type: metric + metric_name: v8js.heap.space.physical_size + brief: "Committed size of a heap space." + instrument: updowncounter + unit: "By" + stability: experimental + prefix: v8js.heap.space.physical_size + attributes: + - ref: v8js.heap.space.name + requirement_level: required + note: > + Value can be retrieved from value `physical_space_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) diff --git a/model/registry/android.yaml b/model/registry/android.yaml index cfdcac8a46..c9c23e46ae 100644 --- a/model/registry/android.yaml +++ b/model/registry/android.yaml @@ -2,6 +2,7 @@ groups: - id: registry.android prefix: android type: attribute_group + display_name: Android Attributes brief: > The Android platform on which the Android application is running. attributes: diff --git a/model/registry/artifact.yaml b/model/registry/artifact.yaml new file mode 100644 index 0000000000..9bed81bbb1 --- /dev/null +++ b/model/registry/artifact.yaml @@ -0,0 +1,97 @@ +groups: + - id: registry.artifact + prefix: artifact + type: attribute_group + brief: > + This group describes attributes specific to artifacts. Artifacts are + files or other immutable objects that are intended for distribution. This + definition aligns directly with the + [SLSA](https://slsa.dev/spec/v1.0/terminology#package-model) package + model. + attributes: + - id: filename + type: string + stability: experimental + brief: > + The human readable file name of the artifact, typically generated + during build and release processes. Often includes the package name + and version in the file name. + note: | + This file name can also act as the [Package Name](https://slsa.dev/spec/v1.0/terminology#package-model) + in cases where the package ecosystem maps accordingly. + Additionally, the artifact [can be published](https://slsa.dev/spec/v1.0/terminology#software-supply-chain) + for others, but that is not a guarantee. + examples: + [ + "golang-binary-amd64-v0.1.0", + "docker-image-amd64-v0.1.0", + "release-1.tar.gz", + "file-name-package.tar.gz", + ] + - id: version + type: string + stability: experimental + brief: > + The version of the artifact. + examples: ["v0.1.0", "1.2.1", "122691-build"] + - id: purl + type: string + stability: experimental + brief: > + The [Package URL](https://github.com/package-url/purl-spec) of the + [package artifact](https://slsa.dev/spec/v1.0/terminology#package-model) + provides a standard way to identify and locate the packaged artifact. + examples: + [ + "pkg:github/package-url/purl-spec@1209109710924", + "pkg:npm/foo@12.12.3", + ] + - id: hash + type: string + stability: experimental + brief: > + The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), + often found in checksum.txt on a release of the artifact and used to + verify package integrity. + note: | + The specific algorithm used to create the cryptographic hash value is + not defined. In situations where an artifact has multiple + cryptographic hashes, it is up to the implementer to choose which + hash value to set here; this should be the most secure hash algorithm + that is suitable for the situation and consistent with the + corresponding attestation. The implementer can then provide the other + hash values through an additional set of attribute extensions as they + deem necessary. + examples: + ["9ff4c52759e2c4ac70b7d517bc7fcdc1cda631ca0045271ddd1b192544f8a3e9"] + - id: attestation.id + type: string + stability: experimental + brief: > + The id of the build [software attestation](https://slsa.dev/attestation-model). + examples: ["123"] + - id: attestation.filename + type: string + stability: experimental + brief: > + The provenance filename of the built attestation which directly + relates to the build artifact filename. This filename SHOULD + accompany the artifact at publish time. See the + [SLSA Relationship](https://slsa.dev/spec/v1.0/distributing-provenance#relationship-between-artifacts-and-attestations) + specification for more information. + examples: + [ + "golang-binary-amd64-v0.1.0.attestation", + "docker-image-amd64-v0.1.0.intoto.json1", + "release-1.tar.gz.attestation", + "file-name-package.tar.gz.intoto.json1", + ] + - id: attestation.hash + type: string + stability: experimental + brief: > + The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), + of the built attestation. Some envelopes in the software attestation + space also refer to this as the [digest](https://github.com/in-toto/attestation/blob/main/spec/README.md#in-toto-attestation-framework-spec). + examples: + ["1b31dfcd5b7f9267bf2ff47651df1cfb9147b9e4df1f335accf65b4cda498408"] diff --git a/model/registry/aspnetcore.yaml b/model/registry/aspnetcore.yaml index 0c93fc1aee..c5e36497e1 100644 --- a/model/registry/aspnetcore.yaml +++ b/model/registry/aspnetcore.yaml @@ -2,6 +2,7 @@ groups: - id: registry.aspnetcore prefix: aspnetcore type: attribute_group + display_name: ASP.NET Core Attributes brief: ASP.NET Core attributes attributes: - id: rate_limiting.policy diff --git a/model/registry/aws.yaml b/model/registry/aws.yaml index 90bb10b853..4ed5f82ff8 100644 --- a/model/registry/aws.yaml +++ b/model/registry/aws.yaml @@ -2,6 +2,7 @@ groups: - id: registry.aws prefix: aws type: attribute_group + display_name: General AWS Attributes brief: > This document defines generic attributes for AWS services. attributes: @@ -15,6 +16,7 @@ groups: - id: registry.aws.dynamodb prefix: aws.dynamodb type: attribute_group + display_name: Amazon DynamoDB Attributes brief: > This document defines attributes for AWS DynamoDB. attributes: @@ -256,6 +258,7 @@ groups: - id: registry.aws.ecs prefix: aws.ecs type: attribute_group + display_name: Amazon ECS Attributes brief: > This document defines attributes for AWS Elastic Container Service (ECS). attributes: @@ -316,6 +319,7 @@ groups: - id: registry.aws.eks prefix: aws.eks type: attribute_group + display_name: Amazon EKS Attributes brief: > This document defines attributes for AWS Elastic Kubernetes Service (EKS). attributes: @@ -328,6 +332,7 @@ groups: - id: registry.aws.log prefix: aws.log type: attribute_group + display_name: Amazon Logs Attributes brief: > This document defines attributes for AWS Logs. attributes: @@ -371,6 +376,7 @@ groups: - id: registry.aws.lambda prefix: aws.lambda type: attribute_group + display_name: Amazon Lambda Attributes brief: > This document defines attributes for AWS Lambda. attributes: @@ -385,6 +391,7 @@ groups: - id: registry.aws.s3 prefix: aws.s3 type: attribute_group + display_name: Amazon S3 Attributes brief: > This document defines attributes for AWS S3. attributes: diff --git a/model/registry/browser.yaml b/model/registry/browser.yaml index fad84c9787..4e6f39c3e3 100644 --- a/model/registry/browser.yaml +++ b/model/registry/browser.yaml @@ -2,6 +2,7 @@ groups: - id: registry.browser prefix: browser type: attribute_group + display_name: Browser Attributes brief: > The web browser attributes attributes: diff --git a/model/registry/cicd.yaml b/model/registry/cicd.yaml new file mode 100644 index 0000000000..16b381274b --- /dev/null +++ b/model/registry/cicd.yaml @@ -0,0 +1,77 @@ +groups: + - id: registry.cicd.pipeline + prefix: cicd.pipeline + type: attribute_group + brief: > + This group describes attributes specific to pipelines within a Continuous + Integration and Continuous Deployment (CI/CD) system. A + [pipeline](https://en.wikipedia.org/wiki/Pipeline_(computing)) in this + case is a series of steps that are performed in order to deliver a new + version of software. This aligns with the + [Britannica](https://www.britannica.com/dictionary/pipeline) definition + of a pipeline where a **pipeline** is the system for developing and + producing something. In the context of CI/CD, a pipeline produces or + delivers software. + attributes: + - id: name + type: string + stability: experimental + brief: > + The human readable name of the pipeline within a CI/CD system. + examples: + [ + "Build and Test", + "Lint", + "Deploy Go Project", + "deploy_to_environment", + ] + - id: run.id + type: string + stability: experimental + brief: > + The unique identifier of a pipeline run within a CI/CD system. + examples: ["120912"] + - id: task.name + type: string + stability: experimental + brief: > + The human readable name of a task within a pipeline. Task here most + closely aligns with a [computing process](https://en.wikipedia.org/wiki/Pipeline_(computing)) + in a pipeline. Other terms for tasks include commands, steps, and + procedures. + examples: ["Run GoLang Linter", "Go Build", "go-test", "deploy_binary"] + - id: task.run.id + type: string + stability: experimental + brief: > + The unique identifier of a task run within a pipeline. + examples: ["12097"] + - id: task.run.url.full + type: string + stability: experimental + brief: > + The [URL](https://en.wikipedia.org/wiki/URL) of the pipeline run + providing the complete address in order to locate and identify the pipeline run. + examples: + [ + "https://github.com/open-telemetry/semantic-conventions/actions/runs/9753949763/job/26920038674?pr=1075", + ] + - id: task.type + type: + members: + - id: build + value: build + brief: build + stability: experimental + - id: test + value: test + brief: test + stability: experimental + - id: deploy + value: deploy + brief: deploy + stability: experimental + stability: experimental + brief: > + The type of the task within a pipeline. + examples: ["build", "test", "deploy"] diff --git a/model/registry/client.yaml b/model/registry/client.yaml index 3b17ed8b4e..507dfd53a7 100644 --- a/model/registry/client.yaml +++ b/model/registry/client.yaml @@ -2,6 +2,7 @@ groups: - id: registry.client prefix: client type: attribute_group + display_name: Client Attributes brief: > 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). diff --git a/model/registry/cloud.yaml b/model/registry/cloud.yaml index ddb83338cc..c86357be9d 100644 --- a/model/registry/cloud.yaml +++ b/model/registry/cloud.yaml @@ -2,6 +2,7 @@ groups: - id: registry.cloud prefix: cloud type: attribute_group + display_name: Cloud Attributes brief: > A cloud environment (e.g. GCP, Azure, AWS). attributes: diff --git a/model/registry/cloudevents.yaml b/model/registry/cloudevents.yaml index 4da702f8a8..61952f29b2 100644 --- a/model/registry/cloudevents.yaml +++ b/model/registry/cloudevents.yaml @@ -2,6 +2,7 @@ groups: - id: registry.cloudevents prefix: cloudevents type: attribute_group + display_name: CloudEvents Attributes brief: > This document defines attributes for CloudEvents. attributes: diff --git a/model/registry/code.yaml b/model/registry/code.yaml index 967607205a..b7119d5150 100644 --- a/model/registry/code.yaml +++ b/model/registry/code.yaml @@ -2,6 +2,7 @@ groups: - id: registry.code prefix: code type: attribute_group + display_name: Code Attributes brief: > These attributes allow to report this unit of code and therefore to provide more context about the span. attributes: diff --git a/model/registry/container.yaml b/model/registry/container.yaml index 60348628b4..750d8854bd 100644 --- a/model/registry/container.yaml +++ b/model/registry/container.yaml @@ -2,6 +2,7 @@ groups: - id: registry.container prefix: container type: attribute_group + display_name: Container Attributes brief: > A container instance. attributes: diff --git a/model/registry/cpu.yaml b/model/registry/cpu.yaml index 43fb145a38..93a327f9fa 100644 --- a/model/registry/cpu.yaml +++ b/model/registry/cpu.yaml @@ -3,6 +3,7 @@ groups: prefix: cpu type: attribute_group brief: Attributes specific to a cpu instance. + display_name: CPU Attributes attributes: - id: mode brief: "The mode of the CPU" diff --git a/model/registry/db.yaml b/model/registry/db.yaml index c94ac32e0f..8529414fbe 100644 --- a/model/registry/db.yaml +++ b/model/registry/db.yaml @@ -2,6 +2,7 @@ groups: - id: registry.db prefix: db type: attribute_group + display_name: General Database Attributes brief: > This group defines the attributes used to describe telemetry in the context of databases. attributes: @@ -340,6 +341,7 @@ groups: - id: registry.db.cassandra prefix: db type: attribute_group + display_name: Cassandra Attributes brief: > This group defines attributes for Cassandra. attributes: @@ -414,6 +416,7 @@ groups: - id: registry.db.cosmosdb prefix: db type: attribute_group + display_name: Azure Cosmos DB Attributes brief: > This group defines attributes for Azure Cosmos DB. attributes: @@ -509,6 +512,7 @@ groups: - id: registry.db.elasticsearch prefix: db type: attribute_group + display_name: Elasticsearch Attributes brief: > This group defines attributes for Elasticsearch. attributes: diff --git a/model/registry/deployment.yaml b/model/registry/deployment.yaml index ffc0050eab..2cf5ec0666 100644 --- a/model/registry/deployment.yaml +++ b/model/registry/deployment.yaml @@ -2,21 +2,48 @@ groups: - id: registry.deployment prefix: deployment type: attribute_group + display_name: Deployment Attributes brief: > This document defines attributes for software deployments. attributes: - - id: environment + - id: name + type: string + stability: experimental + brief: > + The name of the deployment. + examples: ['deploy my app', 'deploy-frontend'] + - id: id + type: string + stability: experimental + brief: > + The id of the deployment. + examples: ['1208'] + - id: status + type: + members: + - id: failed + value: failed + brief: failed + stability: experimental + - id: succeeded + value: succeeded + brief: succeeded + stability: experimental + brief: > + The status of the deployment. + stability: experimental + - id: environment.name 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 + `deployment.environment.name` does not affect the uniqueness constraints defined through the `service.namespace`, `service.name` and `service.instance.id` resource attributes. This implies that resources carrying the following attribute combinations MUST be considered to be identifying the same service: - * `service.name=frontend`, `deployment.environment=production` - * `service.name=frontend`, `deployment.environment=staging`. + * `service.name=frontend`, `deployment.environment.name=production` + * `service.name=frontend`, `deployment.environment.name=staging`. examples: ['staging', 'production'] diff --git a/model/registry/deprecated/android.yaml b/model/registry/deprecated/android.yaml index 97e9bd1e7a..9445a91d5c 100644 --- a/model/registry/deprecated/android.yaml +++ b/model/registry/deprecated/android.yaml @@ -2,6 +2,7 @@ groups: - id: registry.android.deprecated prefix: android type: attribute_group + display_name: Deprecated Android Attributes brief: > This document defines attributes that represents an occurrence of a lifecycle transition on the Android platform. attributes: diff --git a/model/registry/deprecated/container.yaml b/model/registry/deprecated/container.yaml index 63e69621dd..01312d6865 100644 --- a/model/registry/deprecated/container.yaml +++ b/model/registry/deprecated/container.yaml @@ -1,6 +1,7 @@ groups: - id: registry.container.deprecated type: attribute_group + display_name: Deprecated Container Attributes brief: "Describes deprecated container attributes." attributes: - id: container.labels diff --git a/model/registry/deprecated/db.yaml b/model/registry/deprecated/db.yaml index a58a742881..4bdf5f1de3 100644 --- a/model/registry/deprecated/db.yaml +++ b/model/registry/deprecated/db.yaml @@ -2,6 +2,7 @@ groups: - id: registry.db.deprecated prefix: db type: attribute_group + display_name: Deprecated Database Attributes brief: > "Describes deprecated db attributes." attributes: @@ -94,6 +95,7 @@ groups: - id: registry.db.metrics.deprecated type: attribute_group + display_name: Deprecated Database Metrics brief: > "Describes deprecated db metrics attributes." attributes: diff --git a/model/registry/deprecated/deployment.yaml b/model/registry/deprecated/deployment.yaml new file mode 100644 index 0000000000..fa02533e25 --- /dev/null +++ b/model/registry/deprecated/deployment.yaml @@ -0,0 +1,14 @@ +groups: + - id: registry.deployment.deprecated + prefix: deployment + type: attribute_group + brief: > + "Describes deprecated deployment attributes." + attributes: + - id: environment + type: string + stability: experimental + deprecated: 'Deprecated, use `deployment.environment.name` instead.' + brief: > + 'Deprecated, use `deployment.environment.name` instead.' + examples: ['staging', 'production'] diff --git a/model/registry/deprecated/enduser.yaml b/model/registry/deprecated/enduser.yaml index 8908ec8fbd..54e97dcde6 100644 --- a/model/registry/deprecated/enduser.yaml +++ b/model/registry/deprecated/enduser.yaml @@ -2,6 +2,7 @@ groups: - id: registry.enduser.deprecated prefix: enduser type: attribute_group + display_name: Deprecated End User Attributes brief: Describes deprecated enduser attributes. Complete enduser namespace has been deprecated attributes: - id: id diff --git a/model/registry/deprecated/gen-ai.yaml b/model/registry/deprecated/gen-ai.yaml new file mode 100644 index 0000000000..04a2968a74 --- /dev/null +++ b/model/registry/deprecated/gen-ai.yaml @@ -0,0 +1,18 @@ +groups: + - id: registry.gen_ai.deprecated + type: attribute_group + brief: Describes deprecated `gen_ai` attributes. + display_name: Deprecated GenAI Attributes + attributes: + - id: gen_ai.usage.prompt_tokens + type: int + stability: experimental + deprecated: Replaced by `gen_ai.usage.input_tokens` attribute. + brief: "Deprecated, use `gen_ai.usage.input_tokens` instead." + examples: [42] + - id: gen_ai.usage.completion_tokens + type: int + stability: experimental + deprecated: Replaced by `gen_ai.usage.output_tokens` attribute. + brief: "Deprecated, use `gen_ai.usage.output_tokens` instead." + examples: [42] diff --git a/model/registry/deprecated/http.yaml b/model/registry/deprecated/http.yaml index 6fc36ef838..1c35ecdc5e 100644 --- a/model/registry/deprecated/http.yaml +++ b/model/registry/deprecated/http.yaml @@ -1,6 +1,7 @@ groups: - id: registry.http.deprecated type: attribute_group + display_name: Deprecated HTTP Attributes brief: "Describes deprecated HTTP attributes." prefix: http attributes: diff --git a/model/registry/deprecated/ios.yaml b/model/registry/deprecated/ios.yaml index acc1a9f1f9..326a40fcfd 100644 --- a/model/registry/deprecated/ios.yaml +++ b/model/registry/deprecated/ios.yaml @@ -2,6 +2,7 @@ groups: - id: registry.ios.deprecated prefix: ios type: attribute_group + display_name: Deprecated iOS Attributes brief: > The iOS platform on which the iOS application is running. attributes: diff --git a/model/registry/deprecated/k8s.yaml b/model/registry/deprecated/k8s.yaml index e2785dd08e..a928d2d31e 100644 --- a/model/registry/deprecated/k8s.yaml +++ b/model/registry/deprecated/k8s.yaml @@ -1,6 +1,7 @@ groups: - id: registry.k8s.deprecated type: attribute_group + display_name: Deprecated Kubernetes Attributes brief: "Describes deprecated k8s attributes." attributes: - id: k8s.pod.labels diff --git a/model/registry/deprecated/messaging.yaml b/model/registry/deprecated/messaging.yaml index 5f477018ad..8054a9e1ae 100644 --- a/model/registry/deprecated/messaging.yaml +++ b/model/registry/deprecated/messaging.yaml @@ -1,6 +1,7 @@ groups: - id: registry.messaging.deprecated type: attribute_group + display_name: Deprecated Messaging Attributes brief: "Describes deprecated messaging attributes." attributes: - id: messaging.kafka.destination.partition @@ -56,3 +57,22 @@ groups: examples: 'subscription-a' deprecated: > Replaced by `messaging.servicebus.destination.subscription_name`. + - id: messaging.kafka.message.offset + type: int + stability: experimental + brief: > + Deprecated, use `messaging.kafka.offset` instead. + examples: 42 + deprecated: > + Replaced by `messaging.kafka.offset`. + - id: messaging.destination_publish.anonymous + type: boolean + stability: experimental + brief: 'Deprecated, no replacement at this time.' + deprecated: "No replacement at this time." + - id: messaging.destination_publish.name + type: string + stability: experimental + brief: 'Deprecated, no replacement at this time.' + deprecated: "No replacement at this time." + examples: ['MyQueue', 'MyTopic'] diff --git a/model/registry/deprecated/network.yaml b/model/registry/deprecated/network.yaml index f13c79f9a9..7487f69adf 100644 --- a/model/registry/deprecated/network.yaml +++ b/model/registry/deprecated/network.yaml @@ -2,6 +2,7 @@ groups: - id: registry.network.deprecated prefix: net type: attribute_group + display_name: Deprecated Network Attributes brief: > These attributes may be used for any network related operation. attributes: diff --git a/model/registry/deprecated/otel.yaml b/model/registry/deprecated/otel.yaml index c52a51fe8c..b0b9cf0a8b 100644 --- a/model/registry/deprecated/otel.yaml +++ b/model/registry/deprecated/otel.yaml @@ -2,6 +2,7 @@ groups: - id: registry.otel.library.deprecated prefix: otel.library type: attribute_group + display_name: Deprecated OTel Library Attributes brief: "Describes deprecated otel.library attributes." attributes: - id: name diff --git a/model/registry/deprecated/process.yaml b/model/registry/deprecated/process.yaml index 33c5adb0cb..1c79cf81b2 100644 --- a/model/registry/deprecated/process.yaml +++ b/model/registry/deprecated/process.yaml @@ -2,6 +2,7 @@ groups: - id: registry.process.deprecated type: attribute_group brief: "Deprecated process attributes." + display_name: Deprecated Process Attributes attributes: - id: process.cpu.state brief: "Deprecated, use `cpu.mode` instead." diff --git a/model/registry/deprecated/rpc.yaml b/model/registry/deprecated/rpc.yaml index 1d9d22c2d4..e4b37f5d2b 100644 --- a/model/registry/deprecated/rpc.yaml +++ b/model/registry/deprecated/rpc.yaml @@ -1,6 +1,7 @@ groups: - id: registry.rpc.deprecated type: attribute_group + display_name: Deprecated RPC Attributes brief: 'Deprecated rpc message attributes.' attributes: - id: message.type diff --git a/model/registry/deprecated/system.yaml b/model/registry/deprecated/system.yaml index d220a501b7..8f2ece9d84 100644 --- a/model/registry/deprecated/system.yaml +++ b/model/registry/deprecated/system.yaml @@ -1,6 +1,7 @@ groups: - id: registry.system.deprecated type: attribute_group + display_name: Deprecated System Attributes brief: "Deprecated system attributes." attributes: - id: system.processes.status diff --git a/model/registry/deprecated/tls.yaml b/model/registry/deprecated/tls.yaml new file mode 100644 index 0000000000..ebde7b32d4 --- /dev/null +++ b/model/registry/deprecated/tls.yaml @@ -0,0 +1,11 @@ +groups: + - id: registry.tls.deprecated + type: attribute_group + brief: Describes deprecated `tls` attributes. + attributes: + - id: tls.client.server_name + type: string + stability: experimental + deprecated: "Replaced by `server.address." + brief: "Deprecated, use `server.address` instead." + examples: ["opentelemetry.io"] diff --git a/model/registry/destination.yaml b/model/registry/destination.yaml index c05a0c992a..a0631c5201 100644 --- a/model/registry/destination.yaml +++ b/model/registry/destination.yaml @@ -2,6 +2,7 @@ groups: - id: registry.destination prefix: destination type: attribute_group + display_name: Destination Attributes 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. diff --git a/model/registry/device.yaml b/model/registry/device.yaml index 5c324e37fe..901bf1869c 100644 --- a/model/registry/device.yaml +++ b/model/registry/device.yaml @@ -2,6 +2,7 @@ groups: - id: registry.device prefix: device type: attribute_group + display_name: Device Attributes brief: > Describes device attributes. attributes: diff --git a/model/registry/disk.yaml b/model/registry/disk.yaml index aa8c091135..b8dc420351 100644 --- a/model/registry/disk.yaml +++ b/model/registry/disk.yaml @@ -2,6 +2,7 @@ groups: - id: registry.disk prefix: disk type: attribute_group + display_name: Disk Attributes brief: > These attributes may be used for any disk related operation. attributes: diff --git a/model/registry/dns.yaml b/model/registry/dns.yaml index d4042c4add..f58187e0c9 100644 --- a/model/registry/dns.yaml +++ b/model/registry/dns.yaml @@ -1,6 +1,7 @@ groups: - id: registry.dns type: attribute_group + display_name: DNS Attributes prefix: dns brief: > This document defines the shared attributes used to report a DNS query. diff --git a/model/registry/error.yaml b/model/registry/error.yaml index 68bde170ba..95183df639 100644 --- a/model/registry/error.yaml +++ b/model/registry/error.yaml @@ -1,6 +1,7 @@ groups: - id: registry.error type: attribute_group + display_name: Error Attributes prefix: error brief: > This document defines the shared attributes used to report an error. diff --git a/model/registry/event.yaml b/model/registry/event.yaml index 5c246bfdff..0c1e32400e 100644 --- a/model/registry/event.yaml +++ b/model/registry/event.yaml @@ -2,6 +2,7 @@ groups: - id: registry.event prefix: event type: attribute_group + display_name: Event Attributes brief: > Attributes for Events represented using Log Records. attributes: diff --git a/model/registry/exception.yaml b/model/registry/exception.yaml index 70dea3d509..def10422b2 100644 --- a/model/registry/exception.yaml +++ b/model/registry/exception.yaml @@ -1,6 +1,7 @@ groups: - id: registry.exception type: attribute_group + display_name: Exception Attributes prefix: exception brief: > This document defines the shared attributes used to diff --git a/model/registry/faas.yaml b/model/registry/faas.yaml index a4fc8a3d55..6fb139fbf0 100644 --- a/model/registry/faas.yaml +++ b/model/registry/faas.yaml @@ -2,6 +2,7 @@ groups: - id: registry.faas brief: FaaS attributes type: attribute_group + display_name: Function as a Service Attributes prefix: faas attributes: - id: name diff --git a/model/registry/feature-flag.yaml b/model/registry/feature-flag.yaml index 9de106ffc8..1b41ff3898 100644 --- a/model/registry/feature-flag.yaml +++ b/model/registry/feature-flag.yaml @@ -2,6 +2,7 @@ groups: - id: registry.feature_flag prefix: feature_flag type: attribute_group + display_name: Feature Flag Attributes brief: > This document defines attributes for Feature Flags. attributes: diff --git a/model/registry/file.yaml b/model/registry/file.yaml index bbe0f99fd2..57d33a4106 100644 --- a/model/registry/file.yaml +++ b/model/registry/file.yaml @@ -2,6 +2,7 @@ groups: - id: registry.file prefix: file type: attribute_group + display_name: File Attributes brief: "Describes file attributes." attributes: - id: directory diff --git a/model/registry/gcp.yaml b/model/registry/gcp.yaml index 307713df87..66f9273d20 100644 --- a/model/registry/gcp.yaml +++ b/model/registry/gcp.yaml @@ -2,10 +2,12 @@ groups: - id: registry.gcp prefix: gcp type: attribute_group + display_name: GCP Attributes brief: Attributes for Google Cloud - id: registry.gcp.client prefix: gcp.client type: attribute_group + display_name: GCP Client Attributes brief: > Attributes for Google Cloud client libraries. attributes: @@ -22,6 +24,7 @@ groups: - id: registry.gcp.cloud_run prefix: gcp.cloud_run type: attribute_group + display_name: GCP - Google Cloud Run Attributes brief: > This document defines attributes for Google Cloud Run. attributes: @@ -46,6 +49,7 @@ groups: - id: registry.gcp.gce prefix: gcp.gce type: attribute_group + display_name: GCP - Google Compute Engine (GCE) Attributes brief: > This document defines attributes for Google Compute Engine (GCE). attributes: diff --git a/model/registry/gen-ai.yaml b/model/registry/gen-ai.yaml index 2bbf16e7c4..820906f108 100644 --- a/model/registry/gen-ai.yaml +++ b/model/registry/gen-ai.yaml @@ -2,6 +2,7 @@ groups: - id: registry.gen_ai prefix: gen_ai type: attribute_group + display_name: GenAI Attributes brief: > This document defines the attributes used to describe telemetry in the context of Generative Artificial Intelligence (GenAI) Models requests and responses. attributes: @@ -26,7 +27,10 @@ groups: value: "cohere" brief: 'Cohere' brief: The Generative AI product as identified by the client or server instrumentation. - note: > + note: | + The `gen_ai.system` describes a family of GenAI models with specific model identified + by `gen_ai.request.model` and `gen_ai.response.model` attributes. + The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. @@ -90,12 +94,12 @@ groups: type: string[] brief: Array of reasons the model stopped generating tokens, corresponding to each generation received. examples: ['stop'] - - id: usage.prompt_tokens + - id: usage.input_tokens stability: experimental type: int - brief: The number of tokens used in the GenAI input or prompt. + brief: The number of tokens used in the GenAI input (prompt). examples: [100] - - id: usage.completion_tokens + - id: usage.output_tokens stability: experimental type: int brief: The number of tokens used in the GenAI response (completion). @@ -128,6 +132,18 @@ groups: examples: ["[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]"] - id: operation.name stability: experimental - type: string + type: + members: + - id: chat + value: "chat" + brief: 'Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat)' + stability: experimental + - id: text_completion + value: "text_completion" + brief: 'Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions)' + stability: experimental brief: The name of the operation being performed. - examples: ['chat', 'completion'] + note: > + If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic + conventions for specific GenAI system and use system-specific name in the instrumentation. + If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. diff --git a/model/registry/go.yaml b/model/registry/go.yaml index d599102301..2c3727d5c7 100644 --- a/model/registry/go.yaml +++ b/model/registry/go.yaml @@ -1,6 +1,7 @@ groups: - id: registry.go type: attribute_group + display_name: Go Attributes prefix: go brief: > This document defines Go related attributes. diff --git a/model/registry/graphql.yaml b/model/registry/graphql.yaml index 460444d891..ca015d017f 100644 --- a/model/registry/graphql.yaml +++ b/model/registry/graphql.yaml @@ -2,6 +2,7 @@ groups: - id: registry.graphql prefix: graphql type: attribute_group + display_name: GraphQL Attributes brief: 'This document defines attributes for GraphQL.' attributes: - id: operation.name diff --git a/model/registry/heroku.yaml b/model/registry/heroku.yaml index d9fe99a731..f9ff7a85e2 100644 --- a/model/registry/heroku.yaml +++ b/model/registry/heroku.yaml @@ -2,6 +2,7 @@ groups: - id: registry.heroku prefix: heroku type: attribute_group + display_name: Heroku Attributes brief: > This document defines attributes for the Android platform on which the Android application is running. attributes: diff --git a/model/registry/host.yaml b/model/registry/host.yaml index 332ea01f9c..fd2d3db9e1 100644 --- a/model/registry/host.yaml +++ b/model/registry/host.yaml @@ -2,6 +2,7 @@ groups: - id: registry.host prefix: host type: attribute_group + display_name: Host Attributes brief: > A host is defined as a computing instance. For example, physical servers, virtual machines, switches or disk array. attributes: diff --git a/model/registry/http.yaml b/model/registry/http.yaml index e013704a49..71583d4767 100644 --- a/model/registry/http.yaml +++ b/model/registry/http.yaml @@ -2,6 +2,7 @@ groups: - id: registry.http prefix: http type: attribute_group + display_name: HTTP Attributes brief: 'This document defines semantic convention attributes in the HTTP namespace.' attributes: - id: request.body.size diff --git a/model/registry/jvm.yaml b/model/registry/jvm.yaml index 5f3b14f7ec..9ec093f5fe 100644 --- a/model/registry/jvm.yaml +++ b/model/registry/jvm.yaml @@ -1,6 +1,7 @@ groups: - id: registry.jvm type: attribute_group + display_name: Java Virtual Machine (JVM) Attributes prefix: jvm brief: > This document defines Java Virtual machine related attributes. diff --git a/model/registry/k8s.yaml b/model/registry/k8s.yaml index 8b7de837f2..50f38b3132 100644 --- a/model/registry/k8s.yaml +++ b/model/registry/k8s.yaml @@ -2,6 +2,7 @@ groups: - id: registry.k8s prefix: k8s type: attribute_group + display_name: Kubernetes Attributes brief: > Kubernetes resource attributes. attributes: diff --git a/model/registry/linux.yaml b/model/registry/linux.yaml new file mode 100644 index 0000000000..a0f7caef79 --- /dev/null +++ b/model/registry/linux.yaml @@ -0,0 +1,19 @@ +groups: + # linux.memory.* attribute group + - id: registry.linux.memory + prefix: linux.memory + type: attribute_group + brief: "Describes Linux Memory attributes" + attributes: + - id: slab.state + type: + members: + - id: reclaimable + value: 'reclaimable' + stability: experimental + - id: unreclaimable + value: 'unreclaimable' + stability: experimental + stability: experimental + brief: "The Linux Slab memory state" + examples: ["reclaimable", "unreclaimable"] diff --git a/model/registry/log.yaml b/model/registry/log.yaml index b26870a696..399ec35b6b 100644 --- a/model/registry/log.yaml +++ b/model/registry/log.yaml @@ -1,6 +1,7 @@ groups: - id: registry.log type: attribute_group + display_name: General Log Attributes prefix: log brief: > This document defines log attributes @@ -23,6 +24,7 @@ groups: - id: registry.log.file # TODO: should we move it to the file model? type: attribute_group + display_name: Log File Attributes prefix: log.file brief: > Attributes for a file to which log was emitted. @@ -54,6 +56,7 @@ groups: - id: registry.log.record type: attribute_group + display_name: Log Record Attributes prefix: log.record brief: > This document defines the generic attributes that may be used in any Log Record. @@ -70,3 +73,14 @@ groups: 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"] + - id: original + type: string + stability: experimental + brief: > + The complete orignal Log Record. + note: > + This value MAY be added when processing a Log Record which was originally transmitted as a string or equivalent data type AND + the Body field of the Log Record does not contain the same value. (e.g. a syslog or a log record read from a file.) + examples: + - "77 <86>1 2015-08-06T21:58:59.694Z 192.168.2.133 inactive - - - Something happened" + - "[INFO] 8/3/24 12:34:56 Something happened" diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index 5c95891653..f17e8cb5bd 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -2,6 +2,7 @@ groups: - id: registry.messaging prefix: messaging type: attribute_group + display_name: General Messaging Attributes brief: 'Attributes describing telemetry around messaging systems and messaging activities.' attributes: - id: batch.message_count @@ -64,18 +65,6 @@ groups: 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 @@ -217,6 +206,7 @@ groups: - id: registry.messaging.kafka prefix: messaging type: attribute_group + display_name: Kafka Attributes brief: > This group describes attributes specific to Apache Kafka. attributes: @@ -231,7 +221,7 @@ groups: 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 + - id: kafka.offset type: int stability: experimental brief: > @@ -244,6 +234,7 @@ groups: - id: registry.messaging.rabbitmq prefix: messaging type: attribute_group + display_name: RabbitMQ Attributes brief: > This group describes attributes specific to RabbitMQ. attributes: @@ -262,6 +253,7 @@ groups: - id: registry.messaging.rocketmq prefix: messaging type: attribute_group + display_name: RocketMQ Attributes brief: > This group describes attributes specific to RocketMQ. attributes: @@ -342,6 +334,7 @@ groups: - id: registry.messaging.gcp_pubsub prefix: messaging type: attribute_group + display_name: GCP Pub/Sub Attributes brief: > This group describes attributes specific to GCP Pub/Sub. attributes: @@ -372,6 +365,7 @@ groups: - id: registry.messaging.servicebus prefix: messaging type: attribute_group + display_name: Azure Service Bus Attributes brief: > This group describes attributes specific to Azure Service Bus. attributes: @@ -413,6 +407,7 @@ groups: - id: registry.messaging.eventhubs prefix: messaging type: attribute_group + display_name: Azure Event Hubs Attributes brief: > This group describes attributes specific to Azure Event Hubs. attributes: diff --git a/model/registry/network.yaml b/model/registry/network.yaml index 2f3f19576c..847a64c94d 100644 --- a/model/registry/network.yaml +++ b/model/registry/network.yaml @@ -2,6 +2,7 @@ groups: - id: registry.network prefix: network type: attribute_group + display_name: Network Attributes brief: > These attributes may be used for any network related operation. attributes: @@ -194,6 +195,10 @@ groups: value: 'unix' brief: "Unix domain socket" stability: stable + - id: quic + value: 'quic' + brief: "QUIC" + stability: experimental brief: > [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). diff --git a/model/registry/oci.yaml b/model/registry/oci.yaml index 00d0e28c2b..da0ce6dace 100644 --- a/model/registry/oci.yaml +++ b/model/registry/oci.yaml @@ -2,6 +2,7 @@ groups: - id: registry.oci.manifest prefix: oci.manifest type: attribute_group + display_name: Open Container Initiative (OCI) Attributes brief: > An OCI image manifest. attributes: diff --git a/model/registry/opentracing.yaml b/model/registry/opentracing.yaml index fd9d68e380..c5cafc291e 100644 --- a/model/registry/opentracing.yaml +++ b/model/registry/opentracing.yaml @@ -2,6 +2,7 @@ groups: - id: registry.opentracing prefix: opentracing type: attribute_group + display_name: OpenTracing Attributes brief: Attributes used by the OpenTracing Shim layer. attributes: - id: ref_type diff --git a/model/registry/os.yaml b/model/registry/os.yaml index 3317958f16..18b59568a0 100644 --- a/model/registry/os.yaml +++ b/model/registry/os.yaml @@ -2,6 +2,7 @@ groups: - id: registry.os prefix: os type: attribute_group + display_name: Operating System Attributes brief: > The operating system (OS) on which the process represented by this resource is running. note: > diff --git a/model/registry/otel.yaml b/model/registry/otel.yaml index 76286cdc9b..8ed9405a58 100644 --- a/model/registry/otel.yaml +++ b/model/registry/otel.yaml @@ -2,6 +2,7 @@ groups: - id: registry.otel prefix: otel type: attribute_group + display_name: OTel Attributes brief: Attributes reserved for OpenTelemetry attributes: - id: status_code @@ -26,6 +27,7 @@ groups: - id: registry.otel.scope prefix: otel.scope type: attribute_group + display_name: OTel Scope Attributes brief: Attributes used by non-OTLP exporters to represent OpenTelemetry Scope's concepts. attributes: - id: name diff --git a/model/registry/peer.yaml b/model/registry/peer.yaml index a6e38a129d..ee9d3f722f 100644 --- a/model/registry/peer.yaml +++ b/model/registry/peer.yaml @@ -1,6 +1,7 @@ groups: - id: registry.peer type: attribute_group + display_name: Peer Attributes prefix: peer brief: > Operations that access some remote service. diff --git a/model/registry/process.yaml b/model/registry/process.yaml index 7cb7451e66..bc8362357d 100644 --- a/model/registry/process.yaml +++ b/model/registry/process.yaml @@ -2,6 +2,7 @@ groups: - id: registry.process prefix: process type: attribute_group + display_name: Process Attributes brief: > An operating system process. attributes: @@ -130,8 +131,7 @@ groups: type: string stability: experimental brief: > - The name of the runtime of this process. For compiled native binaries, - this SHOULD be the name of the compiler. + The name of the runtime of this process. examples: ['OpenJDK Runtime Environment'] - id: runtime.version type: string diff --git a/model/registry/rpc.yaml b/model/registry/rpc.yaml index d1e0aa05cf..8e04df3224 100644 --- a/model/registry/rpc.yaml +++ b/model/registry/rpc.yaml @@ -2,6 +2,7 @@ groups: - id: registry.rpc prefix: rpc type: attribute_group + display_name: Remote Procedure Call (RPC) Attributes brief: 'This document defines attributes for remote procedure calls.' attributes: - id: connect_rpc.error_code diff --git a/model/registry/server.yaml b/model/registry/server.yaml index d6927fe98a..9da2b85ae1 100644 --- a/model/registry/server.yaml +++ b/model/registry/server.yaml @@ -2,6 +2,7 @@ groups: - id: registry.server prefix: server type: attribute_group + display_name: Server Attributes 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). diff --git a/model/registry/service.yaml b/model/registry/service.yaml index 5af22be57e..44bc2985f6 100644 --- a/model/registry/service.yaml +++ b/model/registry/service.yaml @@ -2,6 +2,7 @@ groups: - id: registry.service prefix: service type: attribute_group + display_name: Service Attributes brief: > A service instance. attributes: diff --git a/model/registry/session.yaml b/model/registry/session.yaml index 3f53c9c6cd..bf39e6ca30 100644 --- a/model/registry/session.yaml +++ b/model/registry/session.yaml @@ -2,6 +2,7 @@ groups: - id: registry.session prefix: session type: attribute_group + display_name: Session Attributes brief: > Session is defined as the period of time encompassing all activities performed by the application and the actions executed by the end user. diff --git a/model/registry/signalr.yaml b/model/registry/signalr.yaml index 879034e7b3..4e87161712 100644 --- a/model/registry/signalr.yaml +++ b/model/registry/signalr.yaml @@ -2,6 +2,7 @@ groups: - id: registry.signalr prefix: signalr type: attribute_group + display_name: SignalR Attributes brief: SignalR attributes attributes: - id: connection.status diff --git a/model/registry/source.yaml b/model/registry/source.yaml index 077da82310..9e0a8af449 100644 --- a/model/registry/source.yaml +++ b/model/registry/source.yaml @@ -2,6 +2,7 @@ groups: - id: registry.source prefix: source type: attribute_group + display_name: Source Attributes 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. diff --git a/model/registry/system.yaml b/model/registry/system.yaml index 790a1374af..c7d8cbc0d8 100644 --- a/model/registry/system.yaml +++ b/model/registry/system.yaml @@ -3,6 +3,7 @@ groups: - id: registry.system prefix: system type: attribute_group + display_name: General System Attributes brief: "Describes System attributes" attributes: - id: device @@ -14,6 +15,7 @@ groups: - id: registry.system.cpu prefix: system.cpu type: attribute_group + display_name: System CPU Attributes brief: "Describes System CPU attributes" attributes: - id: logical_number @@ -25,6 +27,7 @@ groups: - id: registry.system.memory prefix: system.memory type: attribute_group + display_name: System Memory Attributes brief: "Describes System Memory attributes" attributes: - id: state @@ -54,6 +57,7 @@ groups: - id: registry.system.paging prefix: system.paging type: attribute_group + display_name: System Paging Attributes brief: "Describes System Memory Paging attributes" attributes: - id: state @@ -98,6 +102,7 @@ groups: - id: registry.system.filesystem prefix: system.filesystem type: attribute_group + display_name: Filesystem Attributes brief: "Describes Filesystem attributes" attributes: - id: state @@ -155,6 +160,7 @@ groups: - id: registry.system.network prefix: system.network type: attribute_group + display_name: System Network Attributes brief: "Describes Network attributes" attributes: - id: state @@ -204,6 +210,7 @@ groups: - id: registry.system.process prefix: system.process type: attribute_group + display_name: System Process Attributes brief: "Describes System Process attributes" attributes: - id: status diff --git a/model/registry/telemetry.yaml b/model/registry/telemetry.yaml index 2179330323..97b762377a 100644 --- a/model/registry/telemetry.yaml +++ b/model/registry/telemetry.yaml @@ -2,6 +2,7 @@ groups: - id: registry.telemetry prefix: telemetry type: attribute_group + display_name: Telemetry Attributes brief: > This document defines attributes for telemetry SDK. attributes: diff --git a/model/registry/test.yaml b/model/registry/test.yaml new file mode 100644 index 0000000000..3f62dd02f5 --- /dev/null +++ b/model/registry/test.yaml @@ -0,0 +1,79 @@ +groups: + - id: registry.test + prefix: test + type: attribute_group + brief: > + This group describes attributes specific to + [software tests](https://en.wikipedia.org/wiki/Software_testing). + attributes: + - id: suite.name + type: string + stability: experimental + brief: > + The human readable name of a [test suite](https://en.wikipedia.org/wiki/Test_suite). + examples: ["TestSuite1"] + - id: suite.run.status + type: + members: + - id: success + value: success + brief: success + stability: experimental + - id: failure + value: failure + brief: failure + stability: experimental + - id: skipped + value: skipped + brief: skipped + stability: experimental + - id: aborted + value: aborted + brief: aborted + stability: experimental + - id: timed_out + value: timed_out + brief: timed_out + stability: experimental + - id: in_progress + value: in_progress + brief: in_progress + stability: experimental + stability: experimental + brief: > + The status of the test suite run. + examples: + [ + "success", + "failure", + "skipped", + "aborted", + "timed_out", + "in_progress", + ] + - id: case.name + type: string + stability: experimental + brief: > + The fully qualified human readable name of the [test case](https://en.wikipedia.org/wiki/Test_case). + examples: + [ + "org.example.TestCase1.test1", + "example/tests/TestCase1.test1", + "ExampleTestCase1_test1", + ] + - id: case.result.status + type: + members: + - id: pass + value: pass + brief: pass + stability: experimental + - id: fail + value: fail + brief: fail + stability: experimental + stability: experimental + brief: > + The status of the actual test case result from test execution. + examples: ["pass", "fail"] diff --git a/model/registry/thread.yaml b/model/registry/thread.yaml index 9c99772b9b..b6f3556107 100644 --- a/model/registry/thread.yaml +++ b/model/registry/thread.yaml @@ -2,6 +2,7 @@ groups: - id: registry.thread prefix: thread type: attribute_group + display_name: Thread Attributes brief: > These attributes may be used for any operation to store information about a thread that started a span. attributes: diff --git a/model/registry/tls.yaml b/model/registry/tls.yaml index 2c4f31a752..c3d058cfbd 100644 --- a/model/registry/tls.yaml +++ b/model/registry/tls.yaml @@ -2,6 +2,7 @@ groups: - id: registry.tls prefix: tls type: attribute_group + display_name: TLS Attributes brief: "This document defines semantic convention attributes in the TLS namespace." attributes: - id: cipher @@ -73,11 +74,6 @@ groups: 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 diff --git a/model/registry/url.yaml b/model/registry/url.yaml index f979c23a5f..0c808ad5f0 100644 --- a/model/registry/url.yaml +++ b/model/registry/url.yaml @@ -2,6 +2,7 @@ groups: - id: registry.url brief: Attributes describing URL. type: attribute_group + display_name: URL Attributes prefix: url attributes: - id: domain diff --git a/model/registry/user-agent.yaml b/model/registry/user-agent.yaml index 5503454d22..9520c8c5d8 100644 --- a/model/registry/user-agent.yaml +++ b/model/registry/user-agent.yaml @@ -2,6 +2,7 @@ groups: - id: registry.user_agent prefix: user_agent type: attribute_group + display_name: User-agent Attributes brief: "Describes user-agent attributes." attributes: - id: original diff --git a/model/registry/user.yaml b/model/registry/user.yaml index 98792de275..10178f00a8 100644 --- a/model/registry/user.yaml +++ b/model/registry/user.yaml @@ -2,6 +2,7 @@ groups: - id: registry.user prefix: user type: attribute_group + display_name: User Attributes brief: "Describes information about the user." attributes: - id: email diff --git a/model/registry/v8js.yaml b/model/registry/v8js.yaml new file mode 100644 index 0000000000..d39f6e0967 --- /dev/null +++ b/model/registry/v8js.yaml @@ -0,0 +1,55 @@ +groups: + - id: registry.v8js + type: attribute_group + brief: Describes V8 JS Engine Runtime related attributes. + display_name: V8 JS Attributes + prefix: v8js + attributes: + - id: gc.type + stability: experimental + brief: The type of garbage collection. + type: + members: + - id: major + value: 'major' + brief: 'Major (Mark Sweep Compact).' + stability: experimental + - id: minor + value: 'minor' + brief: 'Minor (Scavenge).' + stability: experimental + - id: incremental + value: 'incremental' + brief: 'Incremental (Incremental Marking).' + stability: experimental + - id: weakcb + value: 'weakcb' + brief: 'Weak Callbacks (Process Weak Callbacks).' + stability: experimental + - id: heap.space.name + stability: experimental + brief: The name of the space type of heap memory. + note: > + Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + type: + members: + - id: new_space + value: 'new_space' + brief: 'New memory space.' + stability: experimental + - id: old_space + value: 'old_space' + brief: 'Old memory space.' + stability: experimental + - id: code_space + value: 'code_space' + brief: 'Code memory space.' + stability: experimental + - id: map_space + value: 'map_space' + brief: 'Map memory space.' + stability: experimental + - id: large_object_space + value: 'large_object_space' + brief: 'Large object memory space.' + stability: experimental diff --git a/model/registry/vcs.yaml b/model/registry/vcs.yaml new file mode 100644 index 0000000000..a04ca9122e --- /dev/null +++ b/model/registry/vcs.yaml @@ -0,0 +1,86 @@ +groups: + - id: registry.vcs.repository + prefix: vcs.repository + type: attribute_group + brief: > + This group defines the attributes for + [Version Control Systems (VCS)](https://en.wikipedia.org/wiki/Version_control). + attributes: + - id: url.full + type: string + stability: experimental + brief: > + The [URL](https://en.wikipedia.org/wiki/URL) of the repository + providing the complete address in order to locate and identify the + repository. + examples: + [ + "https://github.com/opentelemetry/open-telemetry-collector-contrib", + "https://gitlab.com/my-org/my-project/my-projects-project/repo", + ] + - id: ref.name + type: string + stability: experimental + brief: > + The name of the + [reference](https://git-scm.com/docs/gitglossary#def_ref) such as + **branch** or **tag** in the repository. + examples: ["my-feature-branch", "tag-1-test"] + - id: ref.type + type: + members: + - id: branch + value: branch + brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)" + stability: experimental + - id: tag + value: tag + brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)" + stability: experimental + stability: experimental + brief: > + The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. + examples: ["branch", "tag"] + - id: ref.revision + type: string + stability: experimental + brief: > + The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), + The revision most often refers to a commit object in Git, or a revision number in SVN. + note: | + The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), + of the recorded change to a ref within a repository pointing to a + commit [commit](https://git-scm.com/docs/git-commit) object. It does + not necessarily have to be a hash; it can simply define a + [revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) + which is an integer that is monotonically increasing. In cases where + it is identical to the `ref.name`, it SHOULD still be included. It is + up to the implementer to decide which value to set as the revision + based on the VCS system and situational context. + examples: + [ + "9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc", + "main", + "123", + "HEAD", + ] + - id: change.title + type: string + stability: experimental + brief: > + The human readable title of the change (pull request/merge request). + This title is often a brief summary of the change and may get merged + in to a ref as the commit summary. + examples: + [ + "Fixes broken thing", + "feat: add my new feature", + "[chore] update dependency", + ] + - id: change.id + type: string + stability: experimental + brief: > + The ID of the change (pull request/merge request) if applicable. This + is usually a unique (within repository) identifier generated by the VCS system. + examples: ["123"] diff --git a/model/registry/webengine.yaml b/model/registry/webengine.yaml index a1579b7d24..97d01e45aa 100644 --- a/model/registry/webengine.yaml +++ b/model/registry/webengine.yaml @@ -2,6 +2,7 @@ groups: - id: registry.webengine prefix: webengine type: attribute_group + display_name: Web Engine Attributes brief: > This document defines the attributes used to describe the packaged software running the application code. attributes: diff --git a/model/resource/deployment_environment.yaml b/model/resource/deployment_environment.yaml index c9a54bc7fa..cd3f2ee518 100644 --- a/model/resource/deployment_environment.yaml +++ b/model/resource/deployment_environment.yaml @@ -4,5 +4,5 @@ groups: brief: > The software deployment. attributes: - - ref: deployment.environment + - ref: deployment.environment.name requirement_level: recommended diff --git a/model/trace/database.yaml b/model/trace/database.yaml index 24d92636dd..36f321d03c 100644 --- a/model/trace/database.yaml +++ b/model/trace/database.yaml @@ -1,10 +1,26 @@ groups: - - id: trace.db.common.query + - id: trace.db.common.minimal extends: attributes.db.client.minimal type: attribute_group brief: This group defines the attributes used to perform database client calls. + attributes: + # TODO: add db.system once https://github.com/open-telemetry/build-tools/issues/192 is possible + # - ref: db.system + # sampling_relevant: true + - ref: db.operation.name + sampling_relevant: true + - ref: server.address + sampling_relevant: true + - ref: server.port + sampling_relevant: true + + - id: trace.db.common.query + extends: trace.db.common.minimal + type: attribute_group + brief: This group defines the attributes used to perform database client calls. attributes: - ref: db.query.text + sampling_relevant: true requirement_level: recommended: > Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes @@ -17,11 +33,12 @@ groups: requirement_level: opt_in - id: trace.db.common.query_and_collection - extends: attributes.db.client.minimal + extends: trace.db.common.minimal type: attribute_group brief: This group defines the attributes used to perform database client calls. attributes: - ref: db.query.text + sampling_relevant: true requirement_level: recommended: > SHOULD be collected by default only if there is sanitization that excludes sensitive information. @@ -29,6 +46,7 @@ groups: - ref: db.query.parameter requirement_level: opt_in - ref: db.collection.name + sampling_relevant: true requirement_level: conditionally_required: > If readily available. The collection name MAY be parsed from the query text, @@ -52,9 +70,11 @@ groups: requirement_level: recommended: if and only if `network.peer.address` is set. - ref: db.system + sampling_relevant: true # TODO: Not adding to the minimal because of https://github.com/open-telemetry/build-tools/issues/192 requirement_level: required - ref: db.namespace + sampling_relevant: true requirement_level: conditionally_required: If available. @@ -72,6 +92,7 @@ groups: Attributes for Microsoft SQL Server attributes: - ref: db.namespace + sampling_relevant: true 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 @@ -88,6 +109,7 @@ groups: Attributes for Cassandra attributes: - ref: db.namespace + sampling_relevant: true 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"] @@ -112,11 +134,12 @@ groups: recommended: if and only if `network.peer.address` is set. - id: db.hbase type: span - extends: attributes.db.client.minimal + extends: trace.db.common.minimal brief: > Attributes for HBase attributes: - ref: db.namespace + sampling_relevant: true brief: The HBase namespace. requirement_level: conditionally_required: If applicable. @@ -126,6 +149,7 @@ groups: instrumentation SHOULD set `db.namespace` value to `default`. examples: ['mynamespace'] - ref: db.collection.name + sampling_relevant: true brief: The HBase table name. requirement_level: conditionally_required: If applicable. @@ -135,11 +159,12 @@ groups: - id: db.couchdb type: span - extends: attributes.db.client.minimal + extends: trace.db.common.minimal brief: > Attributes for CouchDB attributes: - ref: db.operation.name + sampling_relevant: true brief: > The HTTP method + the target REST route. examples: ['GET /{db}/{docid}'] @@ -150,6 +175,7 @@ groups: (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). - ref: db.namespace + sampling_relevant: true requirement_level: conditionally_required: If available. note: "" # overriding the base note @@ -161,8 +187,10 @@ groups: Attributes for Redis attributes: - ref: db.namespace + sampling_relevant: true brief: > - The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select). + The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select) + (captured as a string). requirement_level: conditionally_required: If and only if it can be captured reliably. note: > @@ -175,6 +203,7 @@ groups: For commands that switch the database, this SHOULD be set to the target database (even if the command fails). examples: ["0", "1", "15"] - ref: db.query.text + sampling_relevant: true brief: > The full syntax of the Redis CLI command. examples: ["HMSET myhash field1 'Hello' field2 'World'"] @@ -193,21 +222,24 @@ groups: - id: db.mongodb type: span - extends: attributes.db.client.minimal + extends: trace.db.common.minimal brief: > Attributes for MongoDB attributes: - ref: db.operation.name + sampling_relevant: true brief: > The name of the command being executed. note: > See [MongoDB database commands](https://www.mongodb.com/docs/manual/reference/command/). examples: ['findAndModify', 'getMore', 'update'] - ref: db.collection.name + sampling_relevant: true brief: The MongoDB collection being accessed within the database stated in `db.namespace`. requirement_level: required - ref: db.namespace + sampling_relevant: true brief: The MongoDB database name. requirement_level: conditionally_required: If available. @@ -215,11 +247,12 @@ groups: - id: db.elasticsearch type: span - extends: attributes.db.client.minimal + extends: trace.db.common.minimal brief: > Attributes for Elasticsearch attributes: - ref: http.request.method + sampling_relevant: true requirement_level: required - ref: db.operation.name requirement_level: required @@ -228,9 +261,11 @@ groups: (see the [Elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json)). examples: [ 'search', 'ml.close_job', 'cat.aliases' ] - ref: url.full + sampling_relevant: true requirement_level: required examples: [ 'https://localhost:9200/index/_search?q=user.id:kimchy' ] - ref: db.query.text + sampling_relevant: true requirement_level: recommended: > Should be collected by default for search-type queries and only if there is sanitization that excludes @@ -238,15 +273,15 @@ groups: brief: The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. examples: [ '"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"' ] - ref: db.collection.name + sampling_relevant: true requirement_level: recommended brief: The index or data stream against which the query is executed. note: > The query may target multiple indices or data streams, in which case it SHOULD be a comma separated list of those. If the query doesn't target a specific index, this field MUST NOT be set. examples: [ 'my_index', 'index1, index2' ] - - ref: server.address - - ref: server.port - ref: db.namespace + sampling_relevant: true note: > When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. brief: The name of the Elasticsearch cluster which the client connects to. @@ -341,6 +376,7 @@ groups: requirement_level: conditionally_required: when available - ref: db.namespace + sampling_relevant: true requirement_level: conditionally_required: If available. note: "" # overriding the base note diff --git a/model/trace/gen-ai.yaml b/model/trace/gen-ai.yaml index ef77733e83..9345f4f249 100644 --- a/model/trace/gen-ai.yaml +++ b/model/trace/gen-ai.yaml @@ -12,6 +12,8 @@ groups: The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + - ref: gen_ai.operation.name + requirement_level: required - ref: gen_ai.request.max_tokens requirement_level: recommended - ref: gen_ai.request.temperature @@ -36,10 +38,24 @@ groups: fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. - ref: gen_ai.response.finish_reasons requirement_level: recommended - - ref: gen_ai.usage.prompt_tokens + - ref: gen_ai.usage.input_tokens + requirement_level: recommended + - ref: gen_ai.usage.output_tokens requirement_level: recommended - - ref: gen_ai.usage.completion_tokens + - ref: server.address + brief: GenAI server address. requirement_level: recommended + - ref: server.port + brief: GenAI server port. + requirement_level: + conditionally_required: If `server.address` is set. + - ref: error.type + requirement_level: + conditionally_required: "if the operation ended in an error" + note: | + The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, + the canonical name of exception that occurred, or another low-cardinality error identifier. + Instrumentations SHOULD document the list of errors they report. events: - gen_ai.content.prompt - gen_ai.content.completion diff --git a/model/trace/instrumentation/aws-sdk.yml b/model/trace/instrumentation/aws-sdk.yml index aac648e688..a2ea68a4f8 100644 --- a/model/trace/instrumentation/aws-sdk.yml +++ b/model/trace/instrumentation/aws-sdk.yml @@ -29,16 +29,6 @@ groups: - ref: aws.request_id requirement_level: recommended - - id: dynamodb.all - type: span - brief: "Attributes always filled for all DynamoDB request types." - attributes: - - ref: db.system - brief: "The value `dynamodb`." - requirement_level: required - examples: - - dynamodb - - id: dynamodb.shared extends: aws type: span diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index 52bf65c542..c429f7a542 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -1,25 +1,4 @@ groups: - - 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 - sampling_relevant: true - - ref: messaging.destination_publish.anonymous - - id: attributes.messaging.trace.minimal type: attribute_group brief: > @@ -151,7 +130,7 @@ groups: - ref: messaging.kafka.message.key requirement_level: recommended: If span describes operation on a single message. - - ref: messaging.kafka.message.offset + - ref: messaging.kafka.offset requirement_level: recommended: If span describes operation on a single message. - ref: messaging.kafka.message.tombstone diff --git a/policies/registry.rego b/policies/registry.rego new file mode 100644 index 0000000000..1c73ef450a --- /dev/null +++ b/policies/registry.rego @@ -0,0 +1,42 @@ +package before_resolution + +# This file enforces policies requiring all attributes to be defined within +# a semantic convention "registry". This is a naming/structure convention +# used by semantic conventions. + +# Helper to create attribute registry violations. +attr_registry_violation(violation_id, group_id, attr_id) = violation { + violation := { + "id": violation_id, + "type": "semantic_convention_policies", + "category": "attribute_registry_checks", + "group": group_id, + "attr": attr_id, + } +} + +# We only allow attribute groups in the attribute registry. +deny[attr_registry_violation("attribute_registry_can_only_contain_attribute_groups", group.id, "")] { + group := input.groups[_] + startswith(group.id, "registry.") + group.type != "attribute_group" +} + +# Any group that is NOT in the attribute registry that has an attribute id is +# in violation of not using the attribute registry. +deny[attr_registry_violation("attributes_must_be_defined_in_attribute_registry", group.id, attr.id)] { + group := input.groups[_] + not startswith(group.id, "registry.") + attr := group.attributes[_] + attr.id != null +} + +# A registry `attribute_group` containing at least one `ref` attribute is +# considered invalid if it's not in the registry group. +deny[attr_registry_violation("attributes_in_registry_cannot_reference_each_other", group.id, attr.ref)] { + # TODO - this will need to be updated to support `embed` in the future. + group := input.groups[_] + startswith(group.id, "registry.") + attr := group.attributes[_] + attr.ref != null +} diff --git a/schema-next.yaml b/schema-next.yaml index f87f1059d9..f475f28047 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -4,6 +4,18 @@ versions: next: all: changes: + # https://github.com/open-telemetry/semantic-conventions/pull/1216 + - rename_attributes: + attribute_map: + tls.client.server_name: server.address + # https://github.com/open-telemetry/semantic-conventions/pull/1075 + - rename_attributes: + attribute_map: + deployment.environment: deployment.environment.name + # https://github.com/open-telemetry/semantic-conventions/pull/1245 + - rename_attributes: + attribute_map: + messaging.kafka.message.offset: messaging.kafka.offset # https://github.com/open-telemetry/semantic-conventions/pull/815 - rename_attributes: attribute_map: @@ -11,6 +23,11 @@ versions: messaging.rocketmq.client_group: messaging.consumer.group.name messaging.evenhubs.consumer.group: messaging.consumer.group.name message.servicebus.destination.subscription_name: messaging.destination.subscription.name + # https://github.com/open-telemetry/semantic-conventions/pull/1200 + - rename_attributes: + attribute_map: + gen_ai.usage.completion_tokens: gen_ai.usage.output_tokens + gen_ai.usage.prompt_tokens: gen_ai.usage.input_tokens spans: changes: # https://github.com/open-telemetry/semantic-conventions/pull/1002 @@ -53,6 +70,9 @@ versions: - process.cpu.time - process.cpu.utilization - container.cpu.time + # https://github.com/open-telemetry/semantic-conventions/pull/1265 + - rename_metrics: + jvm.buffer.memory.usage: jvm.buffer.memory.used 1.26.0: metrics: changes: diff --git a/templates/registry/markdown/attribute_macros.j2 b/templates/registry/markdown/attribute_macros.j2 index de9321eae6..7ac1d474c0 100644 --- a/templates/registry/markdown/attribute_macros.j2 +++ b/templates/registry/markdown/attribute_macros.j2 @@ -34,3 +34,10 @@ {%- endif %}{%- elif attribute.type is mapping %} {%- for e in attribute.type.members %}{% if loop.index0 < 3 %}{% if loop.first == false %}; {% endif %}`{{ e.value | trim }}`{% endif %}{%- endfor %} {%- endif %}{% endmacro %} + +{% macro display_name(group) %} +{%- if 'display_name' in group %}{{ group.display_name }} +{%- else %}{{ group.id | split_id | list | reject("eq", "registry") | join(" ") | title_case | acronym }} Attributes +{%- endif %}{% endmacro %} + +{% macro heading_link_fragments(title) %}{{ title | trim | lower | replace(" ", "-") | replace("(", "") | replace(")", "") | replace("/", "") | replace("\\", "") | replace(".", "") | replace("!", "") | replace("?", "") | replace("~", "") | replace("#", "")}}{% endmacro %} diff --git a/templates/registry/markdown/attribute_namespace.md.j2 b/templates/registry/markdown/attribute_namespace.md.j2 index 432943393d..edf210f99d 100644 --- a/templates/registry/markdown/attribute_namespace.md.j2 +++ b/templates/registry/markdown/attribute_namespace.md.j2 @@ -9,6 +9,15 @@ {% import 'attribute_macros.j2' as attrs %} {%- set my_file_name = ctx.id | lower | kebab_case ~ ".md" -%} {{- template.set_file_name(my_file_name) -}} +{%- set groups = namespace(deprecated=[], non_deprecated=[]) -%} +{% for group in ctx.groups | sort(attribute="id") %} +{% if group.id[-10:] == "deprecated" %} +{%- set groups.deprecated = groups.deprecated + [group] -%} +{%- else -%} +{%- set groups.non_deprecated = groups.non_deprecated + [group] -%} +{%- endif -%} +{%- endfor -%} +{%- set attr_groups = groups.non_deprecated + groups.deprecated -%} @@ -18,12 +27,12 @@ # {{ 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 | acronym }} Attributes +{%- if attr_groups | length > 1 %}{% for group in attr_groups %} +- [{{ attrs.display_name(group) }}](#{{ attrs.heading_link_fragments(attrs.display_name(group)) }}) +{%- endfor -%}{%- endif -%} + +{% for group in attr_groups %} +## {{ attrs.display_name(group) }} {{ group.brief }} diff --git a/templates/registry/markdown/weaver.yaml b/templates/registry/markdown/weaver.yaml index f698ae6754..f0d8849c7f 100644 --- a/templates/registry/markdown/weaver.yaml +++ b/templates/registry/markdown/weaver.yaml @@ -9,6 +9,7 @@ acronyms: - AI - iOS - AWS + - CICD - CloudEvents - CPU - CosmosDB @@ -32,3 +33,4 @@ acronyms: - SignalR - TLS - URL + - VCS