From 2ce39aa87d5b773a85e5ac28b6b05ce4766ab8f7 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Wed, 6 Nov 2024 11:24:28 -0500 Subject: [PATCH 01/15] Merge experimental and stable attributes per resource type. (#1423) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/1423.yaml | 23 ++++++++++ docs/resource/README.md | 45 +++++-------------- docs/resource/browser.md | 2 +- model/service/resources-experimental.yaml | 9 ---- model/service/resources.yaml | 2 + model/telemetry/resources-experimental.yaml | 11 ----- model/telemetry/resources.yaml | 11 +++++ policies/group_stability.rego | 8 +++- .../registry/markdown/resource_macros.j2 | 9 +++- templates/registry/markdown/stability.j2 | 1 + 10 files changed, 62 insertions(+), 59 deletions(-) create mode 100644 .chloggen/1423.yaml delete mode 100644 model/service/resources-experimental.yaml delete mode 100644 model/telemetry/resources-experimental.yaml diff --git a/.chloggen/1423.yaml b/.chloggen/1423.yaml new file mode 100644 index 0000000000..ec61d6449c --- /dev/null +++ b/.chloggen/1423.yaml @@ -0,0 +1,23 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: bug_fix + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: service + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: "Merge `resource` experimental and stable groups for service and telemetry.sdk" + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1423] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: | + Discovered when fixing [weaver#306](https://github.com/open-telemetry/weaver/issues/306#issue-2458430277) diff --git a/docs/resource/README.md b/docs/resource/README.md index 3ea6a9c66d..dcf0894001 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -22,9 +22,8 @@ This document defines standard attributes for resources. These attributes are ty - [Semantic Attributes with Dedicated Environment Variable](#semantic-attributes-with-dedicated-environment-variable) - [Semantic Attributes with SDK-provided Default Value](#semantic-attributes-with-sdk-provided-default-value) - [Service](#service) -- [Service (Experimental)](#service-experimental) - [Telemetry SDK](#telemetry-sdk) -- [Telemetry Distribution (Experimental)](#telemetry-distribution-experimental) +- [Telemetry Distro](#telemetry-distro) - [Compute Unit](#compute-unit) - [Compute Instance](#compute-instance) - [Environment](#environment) @@ -81,7 +80,7 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet -**Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) +**Status:** ![Mixed](https://img.shields.io/badge/-mixed-yellow) **type:** `service` @@ -90,37 +89,13 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`service.name`](/docs/attributes-registry/service.md) | string | Logical name of the service. [1] | `shoppingcart` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`service.instance.id`](/docs/attributes-registry/service.md) | string | The string ID of the service instance. [2] | `627cc493-f310-47de-96bd-71410b7dec09` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`service.namespace`](/docs/attributes-registry/service.md) | string | A namespace for `service.name`. [3] | `Shop` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`service.version`](/docs/attributes-registry/service.md) | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. - - - - - -## Service (Experimental) - - - - - - - - - -**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) - -**type:** `service` - -**Description:** A service instance. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`service.instance.id`](/docs/attributes-registry/service.md) | string | The string ID of the service instance. [1] | `627cc493-f310-47de-96bd-71410b7dec09` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`service.namespace`](/docs/attributes-registry/service.md) | string | A namespace for `service.name`. [2] | `Shop` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words +**[2]:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words `service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled service). @@ -147,7 +122,7 @@ However, Collectors can set the `service.instance.id` if they can unambiguously for that telemetry. This is typically the case for scraping receivers, as they know the target address and port. -**[2]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. +**[3]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. @@ -219,9 +194,9 @@ All custom identifiers SHOULD be stable across different versions of an implemen -## Telemetry Distribution (Experimental) +## Telemetry Distro - + @@ -231,9 +206,9 @@ All custom identifiers SHOULD be stable across different versions of an implemen **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -**type:** `telemetry.sdk` +**type:** `telemetry.distro` -**Description:** The telemetry SDK used to capture data recorded by the instrumentation libraries. +**Description:** The distribution of telemetry SDK used to capture data recorded by the instrumentation libraries. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/resource/browser.md b/docs/resource/browser.md index 718e49b7b3..4264df66e3 100644 --- a/docs/resource/browser.md +++ b/docs/resource/browser.md @@ -8,7 +8,7 @@ -**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) +**Status:** ![Mixed](https://img.shields.io/badge/-mixed-yellow) **type:** `browser` diff --git a/model/service/resources-experimental.yaml b/model/service/resources-experimental.yaml deleted file mode 100644 index 861f26862e..0000000000 --- a/model/service/resources-experimental.yaml +++ /dev/null @@ -1,9 +0,0 @@ -groups: - - id: service_experimental - type: resource - name: 'service' - brief: > - A service instance. - attributes: - - ref: service.namespace - - ref: service.instance.id diff --git a/model/service/resources.yaml b/model/service/resources.yaml index b5a3d27f0a..5e24e377c9 100644 --- a/model/service/resources.yaml +++ b/model/service/resources.yaml @@ -9,3 +9,5 @@ groups: - ref: service.name requirement_level: required - ref: service.version + - ref: service.namespace + - ref: service.instance.id diff --git a/model/telemetry/resources-experimental.yaml b/model/telemetry/resources-experimental.yaml deleted file mode 100644 index 6a660cc849..0000000000 --- a/model/telemetry/resources-experimental.yaml +++ /dev/null @@ -1,11 +0,0 @@ -groups: - - id: telemetry.sdk_experimental - type: resource - name: 'telemetry.sdk' - brief: > - The telemetry SDK used to capture data recorded by the instrumentation libraries. - attributes: - - ref: telemetry.distro.name - requirement_level: recommended - - ref: telemetry.distro.version - requirement_level: recommended diff --git a/model/telemetry/resources.yaml b/model/telemetry/resources.yaml index bdd4350b78..42511f5cec 100644 --- a/model/telemetry/resources.yaml +++ b/model/telemetry/resources.yaml @@ -12,3 +12,14 @@ groups: requirement_level: required - ref: telemetry.sdk.version requirement_level: required + - id: telemetry.distro + name: 'telemetry.distro' + type: resource + stability: experimental + brief: > + The distribution of telemetry SDK used to capture data recorded by the instrumentation libraries. + attributes: + - ref: telemetry.distro.name + requirement_level: recommended + - ref: telemetry.distro.version + requirement_level: recommended diff --git a/policies/group_stability.rego b/policies/group_stability.rego index ada9d7baa7..c549709bcb 100644 --- a/policies/group_stability.rego +++ b/policies/group_stability.rego @@ -7,8 +7,12 @@ deny[group_stability_violation(description, group.id, name)] { group.type != "attribute_group" group.stability == "stable" - # TODO: https://github.com/open-telemetry/semantic-conventions/issues/1514 - exceptions = {"metric.kestrel.connection.duration", "metric.kestrel.tls_handshake.duration"} + exceptions = { + # TODO: https://github.com/open-telemetry/semantic-conventions/issues/1514 + "metric.kestrel.connection.duration", "metric.kestrel.tls_handshake.duration", + # TODO: https://github.com/open-telemetry/semantic-conventions/issues/1519 + "service", + } not exceptions[group.id] attr := group.attributes[_] diff --git a/templates/registry/markdown/resource_macros.j2 b/templates/registry/markdown/resource_macros.j2 index 3daa7f1d4d..f19680cbd8 100644 --- a/templates/registry/markdown/resource_macros.j2 +++ b/templates/registry/markdown/resource_macros.j2 @@ -1,7 +1,14 @@ {#- Macros for simplifying creating "Resource" documentation. -#} {% import 'stability.j2' as stability %} +{% macro real_stability(resource) %} +{% if resource.attributes | map(attribute='stability') | unique | length > 1 -%} +{{ stability.badge("mixed", "") }} +{%- else -%} +{{ stability.badge(resource.stability, resource.deprecated) }} +{%- endif %} +{% endmacro %} {% macro header(resource) %} -**Status:** {{ stability.badge(resource.stability, resource.deprecated) }} +**Status:** {{ real_stability(resource) | trim }} **type:** `{{ resource.name }}` diff --git a/templates/registry/markdown/stability.j2 b/templates/registry/markdown/stability.j2 index 0fc901e5da..c623908bac 100644 --- a/templates/registry/markdown/stability.j2 +++ b/templates/registry/markdown/stability.j2 @@ -1,5 +1,6 @@ {% macro badge(stability, deprecated) -%} {%- if deprecated %}![Deprecated](https://img.shields.io/badge/-deprecated-red)
{{ deprecated | trim }} +{%- elif stability == "mixed" %}![Mixed](https://img.shields.io/badge/-mixed-yellow) {%- elif stability == "stable" %}![Stable](https://img.shields.io/badge/-stable-lightgreen) {%- elif stability == "deprecated" %}![Deprecated](https://img.shields.io/badge/-deprecated-red) {%- else %}![Experimental](https://img.shields.io/badge/-experimental-blue) From e0e93bad394a15161af7942d65d197defac7b88b Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 7 Nov 2024 04:24:11 -0800 Subject: [PATCH 02/15] Remove duplicate (#1553) --- model/database/spans.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/model/database/spans.yaml b/model/database/spans.yaml index 9f37b23c3c..551b12bed6 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -22,7 +22,6 @@ groups: stability: experimental brief: This group defines the attributes used to perform database client calls. attributes: - - ref: db.operation.batch.size - ref: db.query.text sampling_relevant: true requirement_level: From 9ef90ae576cf2352cb4c52734a74b1c838d98fc8 Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Fri, 8 Nov 2024 17:15:02 +0100 Subject: [PATCH 03/15] Use project version of markdown-link-check package (#1562) --- .github/workflows/changelog.yml | 13 ++++--------- Makefile | 5 +++++ 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml index a5a390b69d..af8ecb3105 100644 --- a/.github/workflows/changelog.yml +++ b/.github/workflows/changelog.yml @@ -76,13 +76,8 @@ jobs: # In order to validate any links in the yaml file, render the config to markdown - name: Render .chloggen changelog entries - run: make chlog-preview > changelog_preview.md - - name: Install markdown-link-check - run: npm install -g markdown-link-check - - name: Run markdown-link-check run: | - markdown-link-check \ - --verbose \ - --config .markdown_link_check_config.json \ - changelog_preview.md \ - || { echo "Check that anchor links are lowercase"; exit 1; } + make chlog-preview 2> changelog_preview.md + cat changelog_preview.md + - name: Run markdown-link-check + run: markdown-link-check-changelog-preview diff --git a/Makefile b/Makefile index 80b905b8b2..b659346c68 100644 --- a/Makefile +++ b/Makefile @@ -69,6 +69,11 @@ markdown-link-check: || exit 1; \ done +.PHONY: markdown-link-check-changelog-preview +markdown-link-check-changelog-preview: + @if ! npm ls markdown-link-check; then npm install; fi + npx --no -- markdown-link-check --verbose --config .markdown_link_check_config.json changelog_preview.md; + # This target runs markdown-toc on all files that contain # a comment . # From afa2bf8e07620b2d3034c4dac241fe0a14648a5d Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Fri, 8 Nov 2024 17:32:14 +0100 Subject: [PATCH 04/15] Forgot `make` in the workflow command (#1563) --- .github/workflows/changelog.yml | 2 +- Makefile | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml index af8ecb3105..95d54da7bb 100644 --- a/.github/workflows/changelog.yml +++ b/.github/workflows/changelog.yml @@ -80,4 +80,4 @@ jobs: make chlog-preview 2> changelog_preview.md cat changelog_preview.md - name: Run markdown-link-check - run: markdown-link-check-changelog-preview + run: make markdown-link-check-changelog-preview diff --git a/Makefile b/Makefile index b659346c68..fe34a79849 100644 --- a/Makefile +++ b/Makefile @@ -72,7 +72,7 @@ markdown-link-check: .PHONY: markdown-link-check-changelog-preview markdown-link-check-changelog-preview: @if ! npm ls markdown-link-check; then npm install; fi - npx --no -- markdown-link-check --verbose --config .markdown_link_check_config.json changelog_preview.md; + npx --no -- markdown-link-check --quiet --config .markdown_link_check_config.json changelog_preview.md; # This target runs markdown-toc on all files that contain # a comment . From 43f9e308ada81c5ef6851cd665d95f294b157a0f Mon Sep 17 00:00:00 2001 From: Christophe Kamphaus <44020965+christophe-kamphaus-jemmic@users.noreply.github.com> Date: Fri, 8 Nov 2024 18:43:13 +0100 Subject: [PATCH 05/15] Add VCS metrics from Github receiver (#1383) --- .chloggen/1372-vcs-metrics.yaml | 31 ++ .github/CODEOWNERS | 1 + docs/README.md | 1 + docs/attributes-registry/vcs.md | 88 ++++- docs/cicd/cicd-metrics.md | 347 ++++++++++++++++++ model/vcs/deprecated/registry-deprecated.yaml | 61 +++ model/vcs/metrics.yaml | 136 +++++++ model/vcs/registry.yaml | 132 ++++++- schema-next.yaml | 8 + 9 files changed, 791 insertions(+), 14 deletions(-) create mode 100644 .chloggen/1372-vcs-metrics.yaml create mode 100644 docs/cicd/cicd-metrics.md create mode 100644 model/vcs/deprecated/registry-deprecated.yaml create mode 100644 model/vcs/metrics.yaml diff --git a/.chloggen/1372-vcs-metrics.yaml b/.chloggen/1372-vcs-metrics.yaml new file mode 100644 index 0000000000..5c9faded46 --- /dev/null +++ b/.chloggen/1372-vcs-metrics.yaml @@ -0,0 +1,31 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: breaking + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: vcs + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add the VCS metrics inspired by the GitHub Receiver + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1372] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: | + Makes the following changes: + + - Add metrics `vcs.change.count`, `vcs.change.duration`, `vcs.change.time_to_approval`, `vcs.repository.count`, `vcs.ref.count`, + `vcs.ref.lines_delta`, `vcs.ref.revisions_delta`, `vcs.ref.time`, `vcs.contributor.count` + - The VCS attributes `vcs.change.state`, `vcs.revision_delta.direction` and `vcs.line_change.type` have been added to the registry. + - The VCS ref attributes have been duplicated to `vcs.ref.base.*` to allow for ref comparisons. + - The VCS attribute `vcs.ref.type` has been added for simplicity when neither a full head or base ref is necessary. + - `vcs.repository.change.*` attributes have been deprecated and moved to `vcs.change.*`. + - `vcs.repository.ref.*` attributes have been deprecated and moved to `vcs.ref.head.*`. diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index a4307b0262..c0858bd806 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -81,6 +81,7 @@ /model/user/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers # CICD semantic conventions +/docs/cicd/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers /model/artifact/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers /model/cicd/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers /model/code/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers diff --git a/docs/README.md b/docs/README.md index f31cc91fa5..37a3e92c49 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,6 +21,7 @@ The benefit to using Semantic Conventions is in following a common naming scheme Semantic Conventions are defined for the following areas: * **[General](general/README.md): General Semantic Conventions**. +* [CICD](cicd/cicd-metrics.md): Semantic Conventions for CICD systems. * [Cloud Providers](cloud-providers/README.md): Semantic Conventions for cloud providers libraries. * [CloudEvents](cloudevents/README.md): Semantic Conventions for the CloudEvents specification. * [Database](database/README.md): Semantic Conventions for database operations. diff --git a/docs/attributes-registry/vcs.md b/docs/attributes-registry/vcs.md index 82ed2adf9f..15fc8f3f4e 100644 --- a/docs/attributes-registry/vcs.md +++ b/docs/attributes-registry/vcs.md @@ -6,18 +6,28 @@ # VCS +- [VCS Repository Attributes](#vcs-repository-attributes) +- [VCS Deprecated Attributes](#vcs-deprecated-attributes) + ## VCS Repository Attributes This group defines the attributes for [Version Control Systems (VCS)](https://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.change.id` | string | The ID of the change (pull request/merge request/changelist) if applicable. This is usually a unique (within repository) identifier generated by the VCS system. | `123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.change.state` | string | The state of the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.change.title` | string | The human readable title of the change (pull request/merge request/changelist). 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.line_change.type` | string | The type of line change being measured on a branch or change. | `added`; `removed` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.ref.base.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.ref.base.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.ref.base.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.ref.head.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.ref.head.revision` | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [2] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.ref.head.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.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://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) | +| `vcs.revision_delta.direction` | string | The type of revision comparison. | `ahead`; `behind` | ![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 @@ -25,10 +35,76 @@ 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 +it is identical to the `ref.base.name`, it SHOULD still be included. It is up to the implementer to decide which value to set as the revision based on the VCS system and situational context. +**[2]:** The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), +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.head.name`, it SHOULD still be included. It is +up to the implementer to decide which value to set as the revision +based on the VCS system and situational context. + +`vcs.change.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `closed` | Closed means the merge request has been closed without merging. This can happen for various reasons, such as the changes being deemed unnecessary, the issue being resolved in another way, or the author deciding to withdraw the request. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `merged` | Merged indicates that the change has been successfully integrated into the target codebase. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `open` | Open means the change is currently active and under review. It hasn't been merged into the target branch yet, and it's still possible to make changes or add comments. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `wip` | WIP (work-in-progress, draft) means the change is still in progress and not yet ready for a full review. It might still undergo significant changes. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`vcs.line_change.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `added` | How many lines were added. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `removed` | How many lines were removed. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`vcs.ref.base.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `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) | + +`vcs.ref.head.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `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) | + +`vcs.ref.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `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) | + +`vcs.revision_delta.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `ahead` | How many revisions the change is ahead of the target ref. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `behind` | How many revisions the change is behind the target ref. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## VCS Deprecated Attributes + +"Describes deprecated vcs attributes." + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `vcs.repository.change.id` | string | Deprecated, use `vcs.change.id` instead. | `123` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, use `vcs.change.id` instead. | +| `vcs.repository.change.title` | string | Deprecated, use `vcs.change.title` instead. | `Fixes broken thing`; `feat: add my new feature`; `[chore] update dependency` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, use `vcs.change.title` instead. | +| `vcs.repository.ref.name` | string | Deprecated, use `vcs.ref.head.name` instead. | `my-feature-branch`; `tag-1-test` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, use `vcs.ref.head.name` instead. | +| `vcs.repository.ref.revision` | string | Deprecated, use `vcs.ref.head.revision` instead. | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, use `vcs.ref.head.revision` instead. | +| `vcs.repository.ref.type` | string | Deprecated, use `vcs.ref.head.type` instead. | `branch`; `tag` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, use `vcs.ref.head.type` instead. | + `vcs.repository.ref.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/cicd/cicd-metrics.md b/docs/cicd/cicd-metrics.md new file mode 100644 index 0000000000..a0b3244681 --- /dev/null +++ b/docs/cicd/cicd-metrics.md @@ -0,0 +1,347 @@ + + +# Semantic Conventions for CICD Metrics + +**Status**: [Experimental][DocumentStatus] + + + + + +- [VCS Metrics](#vcs-metrics) + - [Metric: `vcs.change.count`](#metric-vcschangecount) + - [Metric: `vcs.change.duration`](#metric-vcschangeduration) + - [Metric: `vcs.change.time_to_approval`](#metric-vcschangetime_to_approval) + - [Metric: `vcs.repository.count`](#metric-vcsrepositorycount) + - [Metric: `vcs.ref.count`](#metric-vcsrefcount) + - [Metric: `vcs.ref.lines_delta`](#metric-vcsreflines_delta) + - [Metric: `vcs.ref.revisions_delta`](#metric-vcsrefrevisions_delta) + - [Metric: `vcs.ref.time`](#metric-vcsreftime) + - [Metric: `vcs.contributor.count`](#metric-vcscontributorcount) + + + +## VCS Metrics + +The conventions described in this section are specific to Version Control Systems. + +**Disclaimer:** These are initial VCS metrics and attributes +but more may be added in the future. + +### Metric: `vcs.change.count` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.change.count` | UpDownCounter | `{change}` | The number of changes (pull requests/merge requests/changelists) in a repository, categorized by their state (e.g. open or merged) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`vcs.change.state`](/docs/attributes-registry/vcs.md) | string | The state of the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`vcs.change.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `closed` | Closed means the merge request has been closed without merging. This can happen for various reasons, such as the changes being deemed unnecessary, the issue being resolved in another way, or the author deciding to withdraw the request. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `merged` | Merged indicates that the change has been successfully integrated into the target codebase. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `open` | Open means the change is currently active and under review. It hasn't been merged into the target branch yet, and it's still possible to make changes or add comments. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `wip` | WIP (work-in-progress, draft) means the change is still in progress and not yet ready for a full review. It might still undergo significant changes. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `vcs.change.duration` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.change.duration` | Gauge | `s` | The time duration a change (pull request/merge request/changelist) has been in a given state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`vcs.change.state`](/docs/attributes-registry/vcs.md) | string | The state of the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`vcs.change.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `closed` | Closed means the merge request has been closed without merging. This can happen for various reasons, such as the changes being deemed unnecessary, the issue being resolved in another way, or the author deciding to withdraw the request. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `merged` | Merged indicates that the change has been successfully integrated into the target codebase. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `open` | Open means the change is currently active and under review. It hasn't been merged into the target branch yet, and it's still possible to make changes or add comments. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `wip` | WIP (work-in-progress, draft) means the change is still in progress and not yet ready for a full review. It might still undergo significant changes. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `vcs.change.time_to_approval` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.change.time_to_approval` | Gauge | `s` | The amount of time since its creation it took a change (pull request/merge request/changelist) to get the first approval | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `vcs.repository.count` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.repository.count` | UpDownCounter | `{repository}` | The number of repositories in an organization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `vcs.ref.count` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.ref.count` | UpDownCounter | `{ref}` | The number of refs of type branch or tag in a repository | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`vcs.ref.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`vcs.ref.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `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) | + + + + + + +### Metric: `vcs.ref.lines_delta` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.ref.lines_delta` | Gauge | `{line}` | The number of lines added/removed in a ref (branch) relative to the ref from the `vcs.ref.base.name` attribute [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This metric should be reported for each `vcs.line_change.type` value. For example if a ref added 3 lines and removed 2 lines, +instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers). +If number of lines added/removed should be calculated from the start of time, then `vcs.ref.base.name` SHOULD be set to an empty string. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`vcs.line_change.type`](/docs/attributes-registry/vcs.md) | string | The type of line change being measured on a branch or change. | `added`; `removed` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.base.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.base.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.change.id`](/docs/attributes-registry/vcs.md) | string | The ID of the change (pull request/merge request/changelist) if applicable. This is usually a unique (within repository) identifier generated by the VCS system. | `123` | `Conditionally Required` if a change is associate with the ref. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`vcs.line_change.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `added` | How many lines were added. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `removed` | How many lines were removed. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`vcs.ref.base.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `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) | + +`vcs.ref.head.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `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) | + + + + + + +### Metric: `vcs.ref.revisions_delta` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.ref.revisions_delta` | Gauge | `{revision}` | The number of revisions (commits) a ref (branch) is ahead/behind the branch from the `vcs.ref.base.name` attribute [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This metric should be reported for each `vcs.revision_delta.direction` value. For example if branch `a` is 3 commits behind and 2 commits ahead of `trunk`, +instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers) and `vcs.ref.base.name` is set to `trunk`. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`vcs.ref.base.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.base.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.revision_delta.direction`](/docs/attributes-registry/vcs.md) | string | The type of revision comparison. | `ahead`; `behind` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.change.id`](/docs/attributes-registry/vcs.md) | string | The ID of the change (pull request/merge request/changelist) if applicable. This is usually a unique (within repository) identifier generated by the VCS system. | `123` | `Conditionally Required` if a change is associate with the ref. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`vcs.ref.base.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `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) | + +`vcs.ref.head.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `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) | + +`vcs.revision_delta.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `ahead` | How many revisions the change is ahead of the target ref. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `behind` | How many revisions the change is behind the target ref. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `vcs.ref.time` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.ref.time` | Gauge | `s` | Time a ref (branch) created from the default branch (trunk) has existed. The `ref.type` attribute will always be `branch` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`vcs.ref.head.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `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) | + + + + + + +### Metric: `vcs.contributor.count` + +This metric is [opt-in][MetricOptIn]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.contributor.count` | Gauge | `{contributor}` | The number of unique contributors to a repository | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/model/vcs/deprecated/registry-deprecated.yaml b/model/vcs/deprecated/registry-deprecated.yaml new file mode 100644 index 0000000000..80ac9b8768 --- /dev/null +++ b/model/vcs/deprecated/registry-deprecated.yaml @@ -0,0 +1,61 @@ +groups: + - id: registry.vcs.deprecated + type: attribute_group + brief: > + "Describes deprecated vcs attributes." + attributes: + - id: vcs.repository.ref.name + type: string + stability: experimental + deprecated: 'Deprecated, use `vcs.ref.head.name` instead.' + brief: > + Deprecated, use `vcs.ref.head.name` instead. + examples: ["my-feature-branch", "tag-1-test"] + - id: vcs.repository.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 + deprecated: 'Deprecated, use `vcs.ref.head.type` instead.' + brief: > + Deprecated, use `vcs.ref.head.type` instead. + examples: ["branch", "tag"] + - id: vcs.repository.ref.revision + type: string + stability: experimental + deprecated: 'Deprecated, use `vcs.ref.head.revision` instead.' + brief: > + Deprecated, use `vcs.ref.head.revision` instead. + examples: + [ + "9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc", + "main", + "123", + "HEAD", + ] + - id: vcs.repository.change.title + type: string + stability: experimental + deprecated: 'Deprecated, use `vcs.change.title` instead.' + brief: > + Deprecated, use `vcs.change.title` instead. + examples: + [ + "Fixes broken thing", + "feat: add my new feature", + "[chore] update dependency", + ] + - id: vcs.repository.change.id + type: string + stability: experimental + deprecated: 'Deprecated, use `vcs.change.id` instead.' + brief: > + Deprecated, use `vcs.change.id` instead. + examples: ["123"] diff --git a/model/vcs/metrics.yaml b/model/vcs/metrics.yaml new file mode 100644 index 0000000000..e2e72f115f --- /dev/null +++ b/model/vcs/metrics.yaml @@ -0,0 +1,136 @@ +groups: + - id: metric.vcs.change.count + type: metric + metric_name: vcs.change.count + brief: 'The number of changes (pull requests/merge requests/changelists) in a repository, categorized by their state (e.g. open or merged)' + instrument: updowncounter + unit: "{change}" + stability: experimental + attributes: + - ref: vcs.change.state + requirement_level: required + - ref: vcs.repository.url.full + requirement_level: required + - id: metric.vcs.change.duration + type: metric + metric_name: vcs.change.duration + brief: 'The time duration a change (pull request/merge request/changelist) has been in a given state.' + instrument: gauge + unit: "s" + stability: experimental + attributes: + - ref: vcs.repository.url.full + requirement_level: required + - ref: vcs.ref.head.name + requirement_level: required + - ref: vcs.change.state + requirement_level: required + - id: metric.vcs.change.time_to_approval + type: metric + metric_name: vcs.change.time_to_approval + brief: 'The amount of time since its creation it took a change (pull request/merge request/changelist) to get the first approval' + instrument: gauge + unit: "s" + stability: experimental + attributes: + - ref: vcs.repository.url.full + requirement_level: required + - ref: vcs.ref.head.name + requirement_level: required + - id: metric.vcs.repository.count + type: metric + metric_name: vcs.repository.count + brief: 'The number of repositories in an organization' + instrument: updowncounter + unit: "{repository}" + stability: experimental + attributes: [] + - id: metric.vcs.ref.count + type: metric + metric_name: vcs.ref.count + brief: 'The number of refs of type branch or tag in a repository' + instrument: updowncounter + unit: "{ref}" + stability: experimental + attributes: + - ref: vcs.repository.url.full + requirement_level: required + - ref: vcs.ref.type + requirement_level: required + - id: metric.vcs.ref.lines_delta + type: metric + metric_name: vcs.ref.lines_delta + brief: 'The number of lines added/removed in a ref (branch) relative to the ref from the `vcs.ref.base.name` attribute' + note: | + This metric should be reported for each `vcs.line_change.type` value. For example if a ref added 3 lines and removed 2 lines, + instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers). + If number of lines added/removed should be calculated from the start of time, then `vcs.ref.base.name` SHOULD be set to an empty string. + instrument: gauge + unit: "{line}" + stability: experimental + attributes: + - ref: vcs.change.id + requirement_level: + conditionally_required: if a change is associate with the ref. + - ref: vcs.repository.url.full + requirement_level: required + - ref: vcs.ref.head.name + requirement_level: required + - ref: vcs.ref.head.type + requirement_level: required + - ref: vcs.ref.base.name + requirement_level: required + - ref: vcs.ref.base.type + requirement_level: required + - ref: vcs.line_change.type + requirement_level: required + - id: metric.vcs.ref.revisions_delta + type: metric + metric_name: vcs.ref.revisions_delta + brief: 'The number of revisions (commits) a ref (branch) is ahead/behind the branch from the `vcs.ref.base.name` attribute' + note: | + This metric should be reported for each `vcs.revision_delta.direction` value. For example if branch `a` is 3 commits behind and 2 commits ahead of `trunk`, + instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers) and `vcs.ref.base.name` is set to `trunk`. + instrument: gauge + unit: "{revision}" + stability: experimental + attributes: + - ref: vcs.change.id + requirement_level: + conditionally_required: if a change is associate with the ref. + - ref: vcs.repository.url.full + requirement_level: required + - ref: vcs.ref.head.name + requirement_level: required + - ref: vcs.ref.head.type + requirement_level: required + - ref: vcs.ref.base.name + requirement_level: required + - ref: vcs.ref.base.type + requirement_level: required + - ref: vcs.revision_delta.direction + requirement_level: required + - id: metric.vcs.ref.time + type: metric + metric_name: vcs.ref.time + brief: 'Time a ref (branch) created from the default branch (trunk) has existed. The `ref.type` attribute will always be `branch`' + instrument: gauge + unit: "s" + stability: experimental + attributes: + - ref: vcs.repository.url.full + requirement_level: required + - ref: vcs.ref.head.name + requirement_level: required + - ref: vcs.ref.head.type + requirement_level: required + - id: metric.vcs.contributor.count + type: metric + metric_name: vcs.contributor.count + brief: 'The number of unique contributors to a repository' + instrument: gauge + unit: "{contributor}" + stability: experimental + attributes: + - ref: vcs.repository.url.full + requirement_level: required diff --git a/model/vcs/registry.yaml b/model/vcs/registry.yaml index 2a0dec19d1..afe703ac53 100644 --- a/model/vcs/registry.yaml +++ b/model/vcs/registry.yaml @@ -17,7 +17,7 @@ groups: "https://github.com/opentelemetry/open-telemetry-collector-contrib", "https://gitlab.com/my-org/my-project/my-projects-project/repo", ] - - id: vcs.repository.ref.name + - id: vcs.ref.base.name type: string stability: experimental brief: > @@ -25,7 +25,7 @@ groups: [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: vcs.repository.ref.type + - id: vcs.ref.base.type type: members: - id: branch @@ -40,7 +40,7 @@ groups: brief: > The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. examples: ["branch", "tag"] - - id: vcs.repository.ref.revision + - id: vcs.ref.base.revision type: string stability: experimental brief: > @@ -53,7 +53,7 @@ groups: 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 + it is identical to the `ref.base.name`, it SHOULD still be included. It is up to the implementer to decide which value to set as the revision based on the VCS system and situational context. examples: @@ -63,11 +63,102 @@ groups: "123", "HEAD", ] - - id: vcs.repository.change.title + - id: vcs.ref.head.name type: string stability: experimental brief: > - The human readable title of the change (pull request/merge request). + 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: vcs.ref.head.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: vcs.ref.head.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.head.name`, it SHOULD still be included. It is + up to the implementer to decide which value to set as the revision + based on the VCS system and situational context. + examples: + [ + "9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc", + "main", + "123", + "HEAD", + ] + - id: vcs.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: vcs.revision_delta.direction + type: + members: + - id: behind + value: behind + brief: "How many revisions the change is behind the target ref." + stability: experimental + - id: ahead + value: ahead + brief: "How many revisions the change is ahead of the target ref." + stability: experimental + stability: experimental + brief: > + The type of revision comparison. + examples: ["ahead", "behind"] + - id: vcs.line_change.type + type: + members: + - id: added + value: added + brief: "How many lines were added." + stability: experimental + - id: removed + value: removed + brief: "How many lines were removed." + stability: experimental + stability: experimental + brief: > + The type of line change being measured on a branch or change. + examples: ["added", "removed"] + - id: vcs.change.title + type: string + stability: experimental + brief: > + The human readable title of the change (pull request/merge request/changelist). This title is often a brief summary of the change and may get merged in to a ref as the commit summary. examples: @@ -76,10 +167,35 @@ groups: "feat: add my new feature", "[chore] update dependency", ] - - id: vcs.repository.change.id + - id: vcs.change.id type: string stability: experimental brief: > - The ID of the change (pull request/merge request) if applicable. This + The ID of the change (pull request/merge request/changelist) if applicable. This is usually a unique (within repository) identifier generated by the VCS system. examples: ["123"] + - id: vcs.change.state + type: + members: + - id: open + value: open + brief: "Open means the change is currently active and under review. It hasn't been merged into the target branch yet, and it's still possible to make changes or add comments." + stability: experimental + - id: wip + value: wip + brief: "WIP (work-in-progress, draft) means the change is still in progress and not yet ready for a full review. It might still undergo significant changes." + stability: experimental + - id: closed + value: closed + brief: >- + Closed means the merge request has been closed without merging. This can happen for various reasons, such as the changes being deemed unnecessary, + the issue being resolved in another way, or the author deciding to withdraw the request. + stability: experimental + - id: merged + value: merged + brief: "Merged indicates that the change has been successfully integrated into the target codebase." + stability: experimental + stability: experimental + brief: > + The state of the change (pull request/merge request/changelist). + examples: ["open", "closed", "merged"] diff --git a/schema-next.yaml b/schema-next.yaml index a3faafd93f..5439843483 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -8,6 +8,14 @@ versions: - rename_attributes: attribute_map: process.executable.build_id.profiling: process.executable.build_id.htlhash + # https://github.com/open-telemetry/semantic-conventions/pull/1383 + - rename_attributes: + attribute_map: + vcs.repository.change.id: vcs.change.id + vcs.repository.change.title: vcs.change.title + vcs.repository.ref.name: vcs.ref.head.name + vcs.repository.ref.revision: vcs.ref.head.revision + vcs.repository.ref.type: vcs.ref.head.type metrics: changes: # https://github.com/open-telemetry/semantic-conventions/pull/1492 From 273056b74d24535294ac9950032188ee8d1ede15 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Sun, 10 Nov 2024 11:38:10 -0800 Subject: [PATCH 06/15] Specific URL query string values should be redacted (#971) Co-authored-by: Liudmila Molkova --- .chloggen/971.yaml | 22 +++++++++++++++++++ docs/attributes-registry/url.md | 39 ++++++++++++++++++++++++++++++--- docs/database/elasticsearch.md | 26 +++++++++++++++++++--- docs/http/http-spans.md | 39 ++++++++++++++++++++++++++++++--- docs/url/url.md | 39 ++++++++++++++++++++++++++++++--- model/url/registry.yaml | 32 +++++++++++++++++++++++++-- 6 files changed, 183 insertions(+), 14 deletions(-) create mode 100644 .chloggen/971.yaml diff --git a/.chloggen/971.yaml b/.chloggen/971.yaml new file mode 100644 index 0000000000..874082aab4 --- /dev/null +++ b/.chloggen/971.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: bug_fix + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: url + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Specific URL query string values should now be redacted by default due to concerns around leaking credentials. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [ 971 ] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/attributes-registry/url.md b/docs/attributes-registry/url.md index ba44a2f815..740bcfd7b1 100644 --- a/docs/attributes-registry/url.md +++ b/docs/attributes-registry/url.md @@ -30,9 +30,29 @@ Attributes describing URL. **[2]:** The file extension is only set if it exists, as not every url has a file extension. When the file name has multiple extensions `example.tar.gz`, only the last one should be captured `gz`, not `tar.gz`. -**[3]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. -`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. -`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. +**[3]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment +is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. + +`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. +In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. + +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). + +Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. + +![Experimental](https://img.shields.io/badge/-experimental-blue) +Query string values for the following keys SHOULD be redacted by default and replaced by the +value `REDACTED`: + +* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token) +* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls) + +This list is subject to change over time. + +When a query string value is redacted, the query string key SHOULD still be preserved, e.g. +`https://www.example.com/path?color=blue&sig=REDACTED`. **[4]:** In network monitoring, the observed URL may be a full URL, whereas in access logs, the URL is often just represented as a path. This field is meant to represent the URL as it was observed, complete or not. `url.original` might contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case password and username SHOULD NOT be redacted and attribute's value SHOULD remain the same. @@ -41,6 +61,19 @@ Attributes describing URL. **[6]:** Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it. +![Experimental](https://img.shields.io/badge/-experimental-blue) +Query string values for the following keys SHOULD be redacted by default and replaced by the value `REDACTED`: + +* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token) +* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls) + +This list is subject to change over time. + +When a query string value is redacted, the query string key SHOULD still be preserved, e.g. +`q=OpenTelemetry&sig=REDACTED`. + **[7]:** This value can be determined precisely with the [public suffix list](http://publicsuffix.org). For example, the registered domain for `foo.example.com` is `example.com`. Trying to approximate this by simply taking the last two labels will not work well for TLDs such as `co.uk`. **[8]:** The subdomain portion of `www.east.mydomain.co.uk` is `east`. If the domain has multiple levels of subdomain, such as `sub2.sub1.example.com`, the subdomain field should contain `sub2.sub1`, with no trailing period. diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 2cccdc5a36..a536172f07 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -56,9 +56,29 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[3]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. -`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. -`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. +**[3]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment +is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. + +`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. +In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. + +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). + +Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. + +![Experimental](https://img.shields.io/badge/-experimental-blue) +Query string values for the following keys SHOULD be redacted by default and replaced by the +value `REDACTED`: + +* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token) +* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls) + +This list is subject to change over time. + +When a query string value is redacted, the query string key SHOULD still be preserved, e.g. +`https://www.example.com/path?color=blue&sig=REDACTED`. **[4]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names. diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 0044d83fce..2073e6891f 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -182,9 +182,29 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[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]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. -`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. -`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. +**[4]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment +is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. + +`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. +In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. + +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). + +Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. + +![Experimental](https://img.shields.io/badge/-experimental-blue) +Query string values for the following keys SHOULD be redacted by default and replaced by the +value `REDACTED`: + +* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token) +* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls) + +This list is subject to change over time. + +When a query string value is redacted, the query string key SHOULD still be preserved, e.g. +`https://www.example.com/path?color=blue&sig=REDACTED`. **[5]:** If the request fails with an error before response status code was sent or received, `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) @@ -434,6 +454,19 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin **[10]:** Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it. +![Experimental](https://img.shields.io/badge/-experimental-blue) +Query string values for the following keys SHOULD be redacted by default and replaced by the value `REDACTED`: + +* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token) +* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls) + +This list is subject to change over time. + +When a query string value is redacted, the query string key SHOULD still be preserved, e.g. +`q=OpenTelemetry&sig=REDACTED`. + **[11]:** The IP address of the original client behind all proxies, if known (e.g. from [Forwarded#for](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#for), [X-Forwarded-For](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-For), or a similar header). Otherwise, the immediate client peer address. **[12]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. diff --git a/docs/url/url.md b/docs/url/url.md index 2128ddc0f4..af52260559 100644 --- a/docs/url/url.md +++ b/docs/url/url.md @@ -37,14 +37,47 @@ This document defines semantic conventions that describe URL and its components. | [`url.query`](/docs/attributes-registry/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [3] | `q=OpenTelemetry` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. -`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. -`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. +**[1]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment +is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. + +`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. +In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. + +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). + +Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. + +![Experimental](https://img.shields.io/badge/-experimental-blue) +Query string values for the following keys SHOULD be redacted by default and replaced by the +value `REDACTED`: + +* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token) +* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls) + +This list is subject to change over time. + +When a query string value is redacted, the query string key SHOULD still be preserved, e.g. +`https://www.example.com/path?color=blue&sig=REDACTED`. **[2]:** Sensitive content provided in `url.path` SHOULD be scrubbed when instrumentations can identify it. **[3]:** Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it. +![Experimental](https://img.shields.io/badge/-experimental-blue) +Query string values for the following keys SHOULD be redacted by default and replaced by the value `REDACTED`: + +* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token) +* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls) + +This list is subject to change over time. + +When a query string value is redacted, the query string key SHOULD still be preserved, e.g. +`q=OpenTelemetry&sig=REDACTED`. + diff --git a/model/url/registry.yaml b/model/url/registry.yaml index dc06b6b2fe..d57c04733e 100644 --- a/model/url/registry.yaml +++ b/model/url/registry.yaml @@ -40,7 +40,7 @@ groups: stability: stable type: string brief: Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) - note: > + note: | For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. @@ -48,7 +48,22 @@ groups: In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. `url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). + Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. + + ![Experimental](https://img.shields.io/badge/-experimental-blue) + Query string values for the following keys SHOULD be redacted by default and replaced by the + value `REDACTED`: + + * [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) + * [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) + * [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token) + * [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls) + + This list is subject to change over time. + + When a query string value is redacted, the query string key SHOULD still be preserved, e.g. + `https://www.example.com/path?color=blue&sig=REDACTED`. examples: ["https://www.foo.bar/search?q=OpenTelemetry#SemConv", "//localhost"] - id: url.original @@ -87,8 +102,21 @@ groups: brief: > The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component examples: ["q=OpenTelemetry"] - note: > + note: | Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it. + + ![Experimental](https://img.shields.io/badge/-experimental-blue) + Query string values for the following keys SHOULD be redacted by default and replaced by the value `REDACTED`: + + * [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) + * [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) + * [`sig`](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview#sas-token) + * [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls) + + This list is subject to change over time. + + When a query string value is redacted, the query string key SHOULD still be preserved, e.g. + `q=OpenTelemetry&sig=REDACTED`. - id: url.registered_domain type: string stability: experimental From 52730dcefed0fa34c5db5a9f781629f173e0e1c6 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 11 Nov 2024 08:16:29 -0800 Subject: [PATCH 07/15] Makes all span/metric/event/resource groups id meaningful (#1512) --- docs/azure/events.md | 2 +- docs/cloud-providers/aws-sdk.md | 2 +- docs/database/cassandra.md | 2 +- docs/database/cosmosdb.md | 2 +- docs/database/couchdb.md | 2 +- docs/database/database-spans.md | 2 +- docs/database/dynamodb.md | 26 ++--- docs/database/elasticsearch.md | 2 +- docs/database/hbase.md | 2 +- docs/database/mariadb.md | 2 +- docs/database/mongodb.md | 2 +- docs/database/mssql.md | 2 +- docs/database/mysql.md | 2 +- docs/database/postgresql.md | 2 +- docs/database/redis.md | 2 +- docs/database/sql.md | 2 +- docs/exceptions/exceptions-spans.md | 2 +- docs/faas/aws-lambda.md | 2 +- docs/faas/faas-spans.md | 10 +- docs/feature-flags/feature-flags-logs.md | 6 +- docs/feature-flags/feature-flags-spans.md | 2 +- docs/gen-ai/gen-ai-spans.md | 2 +- docs/gen-ai/openai.md | 2 +- docs/graphql/graphql-spans.md | 2 +- docs/http/http-spans.md | 4 +- docs/messaging/messaging-spans.md | 2 +- docs/mobile/events.md | 2 +- docs/object-stores/s3.md | 2 +- docs/resource/README.md | 6 +- docs/resource/android.md | 2 +- docs/resource/browser.md | 2 +- docs/resource/cloud-provider/aws/ecs.md | 2 +- docs/resource/cloud-provider/aws/eks.md | 2 +- docs/resource/cloud-provider/aws/logs.md | 2 +- docs/resource/cloud-provider/gcp/cloud-run.md | 2 +- docs/resource/cloud-provider/gcp/gce.md | 2 +- docs/resource/cloud-provider/heroku.md | 14 +-- docs/resource/cloud.md | 2 +- docs/resource/cloudfoundry.md | 10 +- docs/resource/container.md | 2 +- docs/resource/deployment-environment.md | 2 +- docs/resource/device.md | 2 +- docs/resource/faas.md | 2 +- docs/resource/host.md | 4 +- docs/resource/k8s.md | 22 ++-- docs/resource/os.md | 2 +- docs/resource/process.md | 4 +- docs/resource/webengine.md | 2 +- docs/rpc/connect-rpc.md | 2 +- docs/rpc/grpc.md | 2 +- docs/rpc/json-rpc.md | 2 +- docs/rpc/rpc-spans.md | 6 +- model/android/resources.yaml | 2 +- model/aws/ecs-resources.yaml | 2 +- model/aws/eks-resources.yaml | 2 +- model/aws/lambda-spans.yaml | 2 +- model/aws/logs-resources.yaml | 2 +- model/aws/sdk-spans.yml | 106 ++++++++---------- model/azure/{logs.yaml => events.yaml} | 2 +- model/browser/resources.yaml | 2 +- model/cloud/resources.yaml | 2 +- model/cloudevents/spans.yaml | 2 +- model/cloudfoundry/resources.yaml | 10 +- model/container/resources.yaml | 2 +- .../deprecated/metrics-deprecated.yaml | 18 +-- model/database/spans.yaml | 46 +++++--- model/deployment/resources.yaml | 2 +- model/device/events.yaml | 2 +- model/device/resources.yaml | 2 +- model/exceptions/events.yaml | 2 +- model/faas/resources.yaml | 2 +- model/faas/spans.yaml | 10 +- model/feature-flag/events.yaml | 2 +- model/feature-flag/logs.yaml | 11 -- model/gcp/cloud-run-resources.yaml | 2 +- model/gcp/gce-resources.yaml | 2 +- model/gen-ai/events.yaml | 10 +- model/gen-ai/spans.yaml | 6 +- model/graphql/spans.yml | 3 +- model/heroku/resources.yaml | 4 +- model/host/resources.yaml | 4 +- model/http/spans.yaml | 4 +- model/jvm/deprecated/metrics-deprecated.yaml | 2 +- model/k8s/resources.yaml | 22 ++-- model/messaging/spans.yaml | 2 +- model/os/resources.yaml | 2 +- model/otel/resources.yaml | 2 +- model/process/resources.yaml | 4 +- model/rpc/spans.yaml | 18 +-- model/service/resources.yaml | 2 +- model/telemetry/resources.yaml | 6 +- model/webengine/resources.yaml | 2 +- policies/group_stability.rego | 2 +- policies/yaml_schema.rego | 65 +++++++++++ .../attribute_name_collisions_test.rego | 0 .../group_stability_test.rego | 0 .../yaml_schema_test.rego | 59 +++++++++- 97 files changed, 371 insertions(+), 279 deletions(-) rename model/azure/{logs.yaml => events.yaml} (99%) delete mode 100644 model/feature-flag/logs.yaml rename {policies => policies_test}/attribute_name_collisions_test.rego (100%) rename {policies => policies_test}/group_stability_test.rego (100%) rename {policies => policies_test}/yaml_schema_test.rego (55%) diff --git a/docs/azure/events.md b/docs/azure/events.md index 4a32413085..43cc4c8998 100644 --- a/docs/azure/events.md +++ b/docs/azure/events.md @@ -7,7 +7,7 @@ Resource Log events. ## Azure Resource Log - + diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md index 33d6e7bc03..84b936b71d 100644 --- a/docs/cloud-providers/aws-sdk.md +++ b/docs/cloud-providers/aws-sdk.md @@ -24,7 +24,7 @@ The span name MUST be of the format `Service.Operation` as per the AWS HTTP API, with the naming guidelines for RPC client spans. - + diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index ccfa8ad091..b1ac94a8a8 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -12,7 +12,7 @@ The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend a ## Attributes - + diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 3b75b969ae..65e8ccdaec 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -30,7 +30,7 @@ extend and override the [Database Semantic Conventions](database-spans.md). 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. - + diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index 8e38024767..2d5ba06070 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -12,7 +12,7 @@ The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and o ## Attributes - + diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 06c08b0597..88cd2ea50b 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -89,7 +89,7 @@ For example, for an operation describing SQL query on an anonymous table like `S These attributes will usually be the same for all operations performed over the same database connection. - + diff --git a/docs/database/dynamodb.md b/docs/database/dynamodb.md index 9955a2032b..5c55d6ce8c 100644 --- a/docs/database/dynamodb.md +++ b/docs/database/dynamodb.md @@ -13,7 +13,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex ## DynamoDB.BatchGetItem - + @@ -50,7 +50,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex ## DynamoDB.BatchWriteItem - + @@ -88,7 +88,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex ## DynamoDB.CreateTable - + @@ -130,7 +130,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex ## DynamoDB.DeleteItem - + @@ -168,7 +168,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex ## DynamoDB.DeleteTable - + @@ -204,7 +204,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex ## DynamoDB.DescribeTable - + @@ -240,7 +240,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex ## DynamoDB.GetItem - + @@ -279,7 +279,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex ## DynamoDB.ListTables - + @@ -317,7 +317,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex ## DynamoDB.PutItem - + @@ -355,7 +355,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex ## DynamoDB.Query - + @@ -399,7 +399,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex ## DynamoDB.Scan - + @@ -446,7 +446,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex ## DynamoDB.UpdateItem - + @@ -484,7 +484,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex ## DynamoDB.UpdateTable - + diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index a536172f07..ea8f7c0bb7 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -16,7 +16,7 @@ The **span name** follows the [general database span name guidelines](database-s ## Attributes - + diff --git a/docs/database/hbase.md b/docs/database/hbase.md index e7a9f5921a..62bc5a78a5 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -12,7 +12,7 @@ The Semantic Conventions for [HBase](https://hbase.apache.org/) extend and overr ## Attributes - + diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md index 99aced8daf..5df5167326 100644 --- a/docs/database/mariadb.md +++ b/docs/database/mariadb.md @@ -12,7 +12,7 @@ The Semantic Conventions for *MariaDB* extend and override the [Database Semanti ## Attributes - + diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index 05939fca5b..2d4c9a6f85 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -12,7 +12,7 @@ The Semantic Conventions for [MongoDB](https://www.mongodb.com/) extend and over ## Attributes - + diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 35519e5fd6..a2b2f8a313 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -12,7 +12,7 @@ The Semantic Conventions for the *Microsoft SQL Server* extend and override the ## Attributes - + diff --git a/docs/database/mysql.md b/docs/database/mysql.md index 65e273688a..63f2a65692 100644 --- a/docs/database/mysql.md +++ b/docs/database/mysql.md @@ -12,7 +12,7 @@ The Semantic Conventions for *MySQL* extend and override the [Database Semantic ## Attributes - + diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md index 23950fbe41..b4117a9616 100644 --- a/docs/database/postgresql.md +++ b/docs/database/postgresql.md @@ -12,7 +12,7 @@ The Semantic Conventions for *PostgreSQL* extend and override the [Database Sema ## Attributes - + diff --git a/docs/database/redis.md b/docs/database/redis.md index cc09b36948..ac849ee48c 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -12,7 +12,7 @@ The Semantic Conventions for [Redis](https://redis.com/) extend and override the ## Attributes - + diff --git a/docs/database/sql.md b/docs/database/sql.md index 66773c90bd..ff4f78af70 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -36,7 +36,7 @@ Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic co ## Attributes - + diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md index df00c1b87a..03ab3062ac 100644 --- a/docs/exceptions/exceptions-spans.md +++ b/docs/exceptions/exceptions-spans.md @@ -40,7 +40,7 @@ try { ## Exception event - + diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index e408f2cb56..c58c761a70 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -44,7 +44,7 @@ The following attributes SHOULD be set: Also consider setting other attributes of the [`faas` resource][faasres] and [trace][faas] conventions and the [cloud resource conventions][cloud]. The following AWS Lambda-specific attribute MAY also be set: - + diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index 648a9f176b..764eadaa81 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -38,7 +38,7 @@ Span `name` should be set to the function name being executed. Depending on the If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../resource/faas.md). - + @@ -129,7 +129,7 @@ For incoming FaaS spans, the span kind SHOULD be `SERVER`. ### Incoming FaaS Span attributes - + @@ -188,7 +188,7 @@ The values reported by the client for the attributes listed below SHOULD be equa the corresponding [FaaS resource attributes][] and [Cloud resource attributes][], which the invoked FaaS instance reports about itself, if it's instrumented. - + @@ -236,7 +236,7 @@ This section describes how to handle the span creation and additional attributes A datasource function is triggered as a response to some data source operation such as a database or filesystem read/write. FaaS instrumentations that produce `faas` spans with trigger `datasource`, SHOULD use the following set of attributes. - + @@ -279,7 +279,7 @@ This way, it is possible to correlate each individual message with its invocatio A function is scheduled to be executed regularly. The following additional attributes are recommended. - + diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 3ca0dff072..32b2519220 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -37,7 +37,7 @@ context. The table below indicates which attributes should be added to the [LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. - + @@ -48,11 +48,11 @@ The table below indicates which attributes should be added to the The event name MUST be `feature_flag`. -This event describes feature flag evaluation representation on a Log Record. +This event describes feature flag evaluation. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The unique identifier of the feature flag. | `logo-color` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The unique identifier of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.provider_name`](/docs/attributes-registry/feature-flag.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/feature-flags/feature-flags-spans.md b/docs/feature-flags/feature-flags-spans.md index 8ca86c38b8..de0ded12fb 100644 --- a/docs/feature-flags/feature-flags-spans.md +++ b/docs/feature-flags/feature-flags-spans.md @@ -44,7 +44,7 @@ A flag evaluation SHOULD be recorded as an Event on the span during which it occ ### Evaluation event - + diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md index 34c09191e1..4bea84e4d5 100644 --- a/docs/gen-ai/gen-ai-spans.md +++ b/docs/gen-ai/gen-ai-spans.md @@ -34,7 +34,7 @@ Semantic conventions for individual GenAI systems and frameworks MAY specify dif These attributes track input data and metadata for a request to an GenAI model. Each attribute represents a concept that is common to most Generative AI clients. - + diff --git a/docs/gen-ai/openai.md b/docs/gen-ai/openai.md index b72d4912d2..7d77082b70 100644 --- a/docs/gen-ai/openai.md +++ b/docs/gen-ai/openai.md @@ -27,7 +27,7 @@ for [Gen AI Spans](gen-ai-spans.md) and [Gen AI Metrics](gen-ai-metrics.md). These attributes track input data and metadata for a request to an OpenAI model. The attributes include general Generative AI attributes and ones specific the OpenAI. - + diff --git a/docs/graphql/graphql-spans.md b/docs/graphql/graphql-spans.md index d4ab893567..6eee813b07 100644 --- a/docs/graphql/graphql-spans.md +++ b/docs/graphql/graphql-spans.md @@ -22,7 +22,7 @@ the span SHOULD be named `GraphQL Operation`. > span name following `{graphql.operation.type} {graphql.operation.name}` format > when `graphql.operation.name` is available. - + diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 2073e6891f..9ee978c94f 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -131,7 +131,7 @@ This span type represents an outbound HTTP request. There are two ways this can For an HTTP client span, `SpanKind` MUST be `CLIENT`. - + @@ -369,7 +369,7 @@ This span type represents an inbound HTTP request. For an HTTP server span, `SpanKind` MUST be `SERVER`. - + diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 489f42ef8a..cb45f8b28c 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -356,7 +356,7 @@ Messaging attributes are organized into the following namespaces: Messaging system-specific attributes MUST be defined in the corresponding `messaging.{system}` namespace. - + diff --git a/docs/mobile/events.md b/docs/mobile/events.md index d9aa669fce..df2e4bb7e2 100644 --- a/docs/mobile/events.md +++ b/docs/mobile/events.md @@ -20,7 +20,7 @@ application lifecycle. ### Device app lifecycle event - + diff --git a/docs/object-stores/s3.md b/docs/object-stores/s3.md index f5a6bc714f..cb5a1ec093 100644 --- a/docs/object-stores/s3.md +++ b/docs/object-stores/s3.md @@ -11,7 +11,7 @@ The Semantic Conventions for AWS S3 extend the general that describe common AWS SDK attributes in addition to the Semantic Conventions described on this page. - + diff --git a/docs/resource/README.md b/docs/resource/README.md index dcf0894001..ec6365d9e5 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -72,7 +72,7 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet ## Service - + @@ -145,7 +145,7 @@ service.name = Shop.shoppingcart ## Telemetry SDK - + @@ -196,7 +196,7 @@ All custom identifiers SHOULD be stable across different versions of an implemen ## Telemetry Distro - + diff --git a/docs/resource/android.md b/docs/resource/android.md index 9cd4eb0be7..566c707200 100644 --- a/docs/resource/android.md +++ b/docs/resource/android.md @@ -1,6 +1,6 @@ # Android - + diff --git a/docs/resource/browser.md b/docs/resource/browser.md index 4264df66e3..02a356a42e 100644 --- a/docs/resource/browser.md +++ b/docs/resource/browser.md @@ -1,6 +1,6 @@ # Browser - + diff --git a/docs/resource/cloud-provider/aws/ecs.md b/docs/resource/cloud-provider/aws/ecs.md index a926f64352..aacafb958f 100644 --- a/docs/resource/cloud-provider/aws/ecs.md +++ b/docs/resource/cloud-provider/aws/ecs.md @@ -1,6 +1,6 @@ # AWS ECS - + diff --git a/docs/resource/cloud-provider/aws/eks.md b/docs/resource/cloud-provider/aws/eks.md index 6813471103..4511b7e4b3 100644 --- a/docs/resource/cloud-provider/aws/eks.md +++ b/docs/resource/cloud-provider/aws/eks.md @@ -1,6 +1,6 @@ # AWS EKS - + diff --git a/docs/resource/cloud-provider/aws/logs.md b/docs/resource/cloud-provider/aws/logs.md index a3322e49b4..2011ff2d8c 100644 --- a/docs/resource/cloud-provider/aws/logs.md +++ b/docs/resource/cloud-provider/aws/logs.md @@ -1,6 +1,6 @@ # AWS Logs - + diff --git a/docs/resource/cloud-provider/gcp/cloud-run.md b/docs/resource/cloud-provider/gcp/cloud-run.md index fd3529490e..3d85acf964 100644 --- a/docs/resource/cloud-provider/gcp/cloud-run.md +++ b/docs/resource/cloud-provider/gcp/cloud-run.md @@ -4,7 +4,7 @@ These conventions are recommended for resources running on Cloud Run. - + diff --git a/docs/resource/cloud-provider/gcp/gce.md b/docs/resource/cloud-provider/gcp/gce.md index e54735f40a..0175a1357d 100644 --- a/docs/resource/cloud-provider/gcp/gce.md +++ b/docs/resource/cloud-provider/gcp/gce.md @@ -1,6 +1,6 @@ # Google Compute Engine - + diff --git a/docs/resource/cloud-provider/heroku.md b/docs/resource/cloud-provider/heroku.md index f72c344133..aab33c5549 100644 --- a/docs/resource/cloud-provider/heroku.md +++ b/docs/resource/cloud-provider/heroku.md @@ -1,12 +1,6 @@ # Heroku -**Status**: [Experimental][DocumentStatus] - -**type:** `heroku` - -**Description:** [Heroku dyno metadata] - - + @@ -18,7 +12,7 @@ **type:** `heroku` -**Description:** Heroku dyno metadata +**Description:** [Heroku dyno metadata](https://devcenter.heroku.com/articles/dyno-metadata) | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -43,7 +37,3 @@ | `HEROKU_SLUG_COMMIT` | `heroku.release.commit` | Additionally, [the `cloud.provider` resource attribute MUST be set to `heroku`](../cloud.md). - -[Heroku dyno metadata]: https://devcenter.heroku.com/articles/dyno-metadata - -[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/resource/cloud.md b/docs/resource/cloud.md index 0749d14a85..13eeaec65f 100644 --- a/docs/resource/cloud.md +++ b/docs/resource/cloud.md @@ -1,6 +1,6 @@ # Cloud - + diff --git a/docs/resource/cloudfoundry.md b/docs/resource/cloudfoundry.md index c13ec457aa..c789076aa2 100644 --- a/docs/resource/cloudfoundry.md +++ b/docs/resource/cloudfoundry.md @@ -22,7 +22,7 @@ They align with the Bosh deployment tool of CloudFoundry. ## Organization - + @@ -56,7 +56,7 @@ reported by `cf orgs`. ## Space - + @@ -90,7 +90,7 @@ reported by `cf spaces`. ## Application - + @@ -124,7 +124,7 @@ as reported by `cf apps`. ## Process - + @@ -159,7 +159,7 @@ tasks or side-cars with different process types. ## Cloud Foundry System Component - + diff --git a/docs/resource/container.md b/docs/resource/container.md index db7158f608..89ffe0b9b4 100644 --- a/docs/resource/container.md +++ b/docs/resource/container.md @@ -1,6 +1,6 @@ # Container - + diff --git a/docs/resource/deployment-environment.md b/docs/resource/deployment-environment.md index 2bb9e07e73..8499e2cf08 100644 --- a/docs/resource/deployment-environment.md +++ b/docs/resource/deployment-environment.md @@ -1,6 +1,6 @@ # Deployment - + diff --git a/docs/resource/device.md b/docs/resource/device.md index b8e4f6cb6c..ae60eb783c 100644 --- a/docs/resource/device.md +++ b/docs/resource/device.md @@ -1,6 +1,6 @@ # Device - + diff --git a/docs/resource/faas.md b/docs/resource/faas.md index accb79298d..2f8ecd5711 100644 --- a/docs/resource/faas.md +++ b/docs/resource/faas.md @@ -7,7 +7,7 @@ See also: ## FaaS resource attributes - + diff --git a/docs/resource/host.md b/docs/resource/host.md index 073a167198..fe08de147b 100644 --- a/docs/resource/host.md +++ b/docs/resource/host.md @@ -3,7 +3,7 @@ The `host.*` namespace SHOULD be exclusively used to capture resource attributes. To report host metrics, the `system.*` namespace SHOULD be used. - + @@ -79,7 +79,7 @@ privileged lookup of `host.id` is required, the value should be injected via the **type:** `host.cpu` - + diff --git a/docs/resource/k8s.md b/docs/resource/k8s.md index efbd40327f..64d01eb13a 100644 --- a/docs/resource/k8s.md +++ b/docs/resource/k8s.md @@ -17,7 +17,7 @@ Kubernetes object, but "name" is usually more user friendly so can be also set. ## Cluster - + @@ -66,7 +66,7 @@ conflict. ## Node - + @@ -95,7 +95,7 @@ conflict. Namespaces provide a scope for names. Names of objects need to be unique within a namespace, but not across namespaces. - + @@ -123,7 +123,7 @@ a namespace, but not across namespaces. The smallest and simplest Kubernetes object. A Pod represents a set of running containers on your cluster. - + @@ -158,7 +158,7 @@ from the name of the running container. Note: This type is different from [container](./container.md), which corresponds to a running container. - + @@ -185,7 +185,7 @@ to a running container. ## ReplicaSet - + @@ -215,7 +215,7 @@ An API object that manages a replicated application, typically by running Pods with no local state. Each replica is represented by a Pod, and the Pods are distributed among the nodes of a cluster. - + @@ -244,7 +244,7 @@ distributed among the nodes of a cluster. Manages the deployment and scaling of a set of Pods, and provides guarantees about the ordering and uniqueness of these Pods. - + @@ -272,7 +272,7 @@ about the ordering and uniqueness of these Pods. A DaemonSet ensures that all (or some) Nodes run a copy of a Pod. - + @@ -301,7 +301,7 @@ A DaemonSet ensures that all (or some) Nodes run a copy of a Pod. A Job creates one or more Pods and ensures that a specified number of them successfully terminate. - + @@ -329,7 +329,7 @@ successfully terminate. A CronJob creates Jobs on a repeating schedule. - + diff --git a/docs/resource/os.md b/docs/resource/os.md index 4ea20d3051..6a5c2c16c0 100644 --- a/docs/resource/os.md +++ b/docs/resource/os.md @@ -2,7 +2,7 @@ In case of virtualized environments, this is the operating system as it is observed by the process, i.e., the virtualized guest rather than the underlying host. - + diff --git a/docs/resource/process.md b/docs/resource/process.md index 8e48ae165c..97bd2e2e64 100644 --- a/docs/resource/process.md +++ b/docs/resource/process.md @@ -21,7 +21,7 @@ ## Process - + @@ -77,7 +77,7 @@ On Windows and other systems where the native format of process commands is a si ## Process runtimes - + diff --git a/docs/resource/webengine.md b/docs/resource/webengine.md index 7c8e7d4ed3..922fcd71fe 100644 --- a/docs/resource/webengine.md +++ b/docs/resource/webengine.md @@ -1,6 +1,6 @@ # Webengine - + diff --git a/docs/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md index 5d85046ab7..062cc07fd7 100644 --- a/docs/rpc/connect-rpc.md +++ b/docs/rpc/connect-rpc.md @@ -16,7 +16,7 @@ described on this page. Below is a table of attributes that SHOULD be included on client and server Connect RPC measurements. - + diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md index a21cfdb832..f5e4a92a0c 100644 --- a/docs/rpc/grpc.md +++ b/docs/rpc/grpc.md @@ -16,7 +16,7 @@ described on this page. Below is a table of attributes that SHOULD be included on client and server gRPC measurements. - + diff --git a/docs/rpc/json-rpc.md b/docs/rpc/json-rpc.md index d242d9b8ec..41e1458fb4 100644 --- a/docs/rpc/json-rpc.md +++ b/docs/rpc/json-rpc.md @@ -14,7 +14,7 @@ described on this page. `rpc.system` MUST be set to `"jsonrpc"`. - + diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 3a34471797..f04c37a118 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -95,7 +95,7 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service ### Client attributes - + @@ -166,7 +166,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. ### Server attributes - + @@ -245,7 +245,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. #### Message event - + diff --git a/model/android/resources.yaml b/model/android/resources.yaml index 7138bc2902..9070a37688 100644 --- a/model/android/resources.yaml +++ b/model/android/resources.yaml @@ -1,5 +1,5 @@ groups: - - id: android + - id: resource.android type: resource name: android brief: > diff --git a/model/aws/ecs-resources.yaml b/model/aws/ecs-resources.yaml index 7b14ff129c..44cc06b9e6 100644 --- a/model/aws/ecs-resources.yaml +++ b/model/aws/ecs-resources.yaml @@ -1,5 +1,5 @@ groups: - - id: aws.ecs + - id: resource.aws.ecs type: resource name: aws.ecs brief: > diff --git a/model/aws/eks-resources.yaml b/model/aws/eks-resources.yaml index ea849dfed9..5b8d142969 100644 --- a/model/aws/eks-resources.yaml +++ b/model/aws/eks-resources.yaml @@ -1,5 +1,5 @@ groups: - - id: aws.eks + - id: resource.aws.eks type: resource name: aws.eks brief: > diff --git a/model/aws/lambda-spans.yaml b/model/aws/lambda-spans.yaml index 41943ab8cb..934795bc40 100644 --- a/model/aws/lambda-spans.yaml +++ b/model/aws/lambda-spans.yaml @@ -1,5 +1,5 @@ groups: - - id: aws.lambda + - id: span.aws.lambda type: span brief: > Span attributes used by AWS Lambda (in addition to general `faas` attributes). diff --git a/model/aws/logs-resources.yaml b/model/aws/logs-resources.yaml index b5b379dfdf..4c09b07570 100644 --- a/model/aws/logs-resources.yaml +++ b/model/aws/logs-resources.yaml @@ -1,5 +1,5 @@ groups: - - id: aws.log + - id: resource.aws.log type: resource name: aws.log brief: > diff --git a/model/aws/sdk-spans.yml b/model/aws/sdk-spans.yml index 6dbe1d3211..4ac5ccc369 100644 --- a/model/aws/sdk-spans.yml +++ b/model/aws/sdk-spans.yml @@ -1,6 +1,7 @@ groups: - - id: aws + - id: span.aws.client type: span + span_kind: client brief: > The `aws` conventions apply to operations using the AWS SDK. They map request or response parameters in AWS SDK API calls to attributes on a Span. The conventions have been collected over time based @@ -28,53 +29,22 @@ groups: - ref: aws.request_id requirement_level: recommended - - id: dynamodb.shared - extends: aws - type: span - brief: "Attributes that exist for multiple DynamoDB request types." - attributes: - - ref: db.operation.name - brief: "The same value as `rpc.method`." - examples: - - GetItem - - PutItem - - ref: aws.dynamodb.table_names - requirement_level: recommended - - ref: aws.dynamodb.consumed_capacity - requirement_level: recommended - - ref: aws.dynamodb.item_collection_metrics - requirement_level: recommended - - ref: aws.dynamodb.provisioned_read_capacity - requirement_level: recommended - - ref: aws.dynamodb.provisioned_write_capacity - requirement_level: recommended - - ref: aws.dynamodb.consistent_read - requirement_level: recommended - - ref: aws.dynamodb.projection - requirement_level: recommended - - ref: aws.dynamodb.limit - requirement_level: recommended - - ref: aws.dynamodb.attributes_to_get - requirement_level: recommended - - ref: aws.dynamodb.index_name - requirement_level: recommended - - ref: aws.dynamodb.select - requirement_level: recommended - - - id: dynamodb.batchgetitem + - id: span.dynamodb.batchgetitem.client brief: DynamoDB.BatchGetItem - extends: aws + extends: span.aws.client type: span + span_kind: client attributes: - ref: aws.dynamodb.table_names requirement_level: recommended - ref: aws.dynamodb.consumed_capacity requirement_level: recommended - - id: dynamodb.batchwriteitem + - id: span.dynamodb.batchwriteitem.client brief: DynamoDB.BatchWriteItem - extends: aws + extends: span.aws.client type: span + span_kind: client attributes: - ref: aws.dynamodb.table_names requirement_level: recommended @@ -83,10 +53,11 @@ groups: - ref: aws.dynamodb.item_collection_metrics requirement_level: recommended - - id: dynamodb.createtable + - id: span.dynamodb.createtable.client brief: DynamoDB.CreateTable - extends: aws + extends: span.aws.client type: span + span_kind: client attributes: - ref: aws.dynamodb.global_secondary_indexes requirement_level: recommended @@ -106,10 +77,11 @@ groups: - ref: aws.dynamodb.provisioned_write_capacity requirement_level: recommended - - id: dynamodb.deleteitem + - id: span.dynamodb.deleteitem.client brief: DynamoDB.DeleteItem - extends: aws + extends: span.aws.client type: span + span_kind: client attributes: - ref: aws.dynamodb.table_names requirement_level: recommended @@ -121,10 +93,11 @@ groups: - ref: aws.dynamodb.item_collection_metrics requirement_level: recommended - - id: dynamodb.deletetable + - id: span.dynamodb.deletetable.client brief: DynamoDB.DeleteTable - extends: aws + extends: span.aws.client type: span + span_kind: client attributes: - ref: aws.dynamodb.table_names requirement_level: recommended @@ -132,10 +105,11 @@ groups: examples: - Users - - id: dynamodb.describetable + - id: span.dynamodb.describetable.client brief: DynamoDB.DescribeTable - extends: aws + extends: span.aws.client type: span + span_kind: client attributes: - ref: aws.dynamodb.table_names requirement_level: recommended @@ -143,10 +117,11 @@ groups: examples: - Users - - id: dynamodb.getitem + - id: span.dynamodb.getitem.client brief: DynamoDB.GetItem - extends: aws + extends: span.aws.client type: span + span_kind: client attributes: - ref: aws.dynamodb.table_names requirement_level: recommended @@ -160,10 +135,11 @@ groups: - ref: aws.dynamodb.projection requirement_level: recommended - - id: dynamodb.listtables + - id: span.dynamodb.listtables.client brief: DynamoDB.ListTables - extends: aws + extends: span.aws.client type: span + span_kind: client attributes: - ref: aws.dynamodb.exclusive_start_table requirement_level: recommended @@ -172,10 +148,11 @@ groups: - ref: aws.dynamodb.limit requirement_level: recommended - - id: dynamodb.putitem + - id: span.dynamodb.putitem.client brief: DynamoDB.PutItem - extends: aws + extends: span.aws.client type: span + span_kind: client attributes: - ref: aws.dynamodb.table_names requirement_level: recommended @@ -184,10 +161,11 @@ groups: - ref: aws.dynamodb.item_collection_metrics requirement_level: recommended - - id: dynamodb.query + - id: span.dynamodb.query.client brief: DynamoDB.Query - extends: aws + extends: span.aws.client type: span + span_kind: client attributes: - ref: aws.dynamodb.scan_forward requirement_level: recommended @@ -211,10 +189,11 @@ groups: - ref: aws.dynamodb.select requirement_level: recommended - - id: dynamodb.scan + - id: span.dynamodb.scan.client brief: DynamoDB.Scan - extends: aws + extends: span.aws.client type: span + span_kind: client attributes: - ref: aws.dynamodb.segment requirement_level: recommended @@ -244,10 +223,11 @@ groups: - ref: aws.dynamodb.select requirement_level: recommended - - id: dynamodb.updateitem + - id: span.dynamodb.updateitem.client brief: DynamoDB.UpdateItem - extends: aws + extends: span.aws.client type: span + span_kind: client attributes: - ref: aws.dynamodb.table_names requirement_level: recommended @@ -259,10 +239,11 @@ groups: - ref: aws.dynamodb.item_collection_metrics requirement_level: recommended - - id: dynamodb.updatetable + - id: span.dynamodb.updatetable.client brief: DynamoDB.UpdateTable - extends: aws + extends: span.aws.client type: span + span_kind: client attributes: - ref: aws.dynamodb.attribute_definitions requirement_level: recommended @@ -280,9 +261,10 @@ groups: - ref: aws.dynamodb.provisioned_write_capacity requirement_level: recommended - - id: aws.s3 - extends: aws + - id: span.aws.s3.client + extends: span.aws.client type: span + span_kind: client brief: "Attributes that exist for S3 request types." attributes: - ref: aws.s3.bucket diff --git a/model/azure/logs.yaml b/model/azure/events.yaml similarity index 99% rename from model/azure/logs.yaml rename to model/azure/events.yaml index 4a5e3fc22a..ee7b08f2b6 100644 --- a/model/azure/logs.yaml +++ b/model/azure/events.yaml @@ -1,5 +1,5 @@ groups: - - id: az.resource.log + - id: event.az.resource.log stability: experimental type: event name: az.resource.log diff --git a/model/browser/resources.yaml b/model/browser/resources.yaml index df8492cd60..01b31567f7 100644 --- a/model/browser/resources.yaml +++ b/model/browser/resources.yaml @@ -1,5 +1,5 @@ groups: - - id: browser + - id: resource.browser type: resource name: browser brief: > diff --git a/model/cloud/resources.yaml b/model/cloud/resources.yaml index 954ff0ad1b..0daa6fdf9f 100644 --- a/model/cloud/resources.yaml +++ b/model/cloud/resources.yaml @@ -1,5 +1,5 @@ groups: - - id: cloud + - id: resource.cloud type: resource name: cloud brief: > diff --git a/model/cloudevents/spans.yaml b/model/cloudevents/spans.yaml index 604d101c17..8c7dd6039d 100644 --- a/model/cloudevents/spans.yaml +++ b/model/cloudevents/spans.yaml @@ -1,6 +1,6 @@ groups: - id: cloudevents - type: span + type: attribute_group brief: > This document defines attributes for CloudEvents. CloudEvents is a specification on how to define event data in a standard way. diff --git a/model/cloudfoundry/resources.yaml b/model/cloudfoundry/resources.yaml index 95d60abe35..40d8c235bb 100644 --- a/model/cloudfoundry/resources.yaml +++ b/model/cloudfoundry/resources.yaml @@ -1,5 +1,5 @@ groups: - - id: cloudfoundry.system + - id: resource.cloudfoundry.system type: resource name: cloudfoundry.system brief: > @@ -7,7 +7,7 @@ groups: attributes: - ref: cloudfoundry.system.id - ref: cloudfoundry.system.instance.id - - id: cloudfoundry.app + - id: resource.cloudfoundry.app type: resource name: cloudfoundry.app brief: > @@ -15,7 +15,7 @@ groups: attributes: - ref: cloudfoundry.app.id - ref: cloudfoundry.app.name - - id: cloudfoundry.space + - id: resource.cloudfoundry.space type: resource name: cloudfoundry.space brief: > @@ -23,7 +23,7 @@ groups: attributes: - ref: cloudfoundry.space.id - ref: cloudfoundry.space.name - - id: cloudfoundry.org + - id: resource.cloudfoundry.org type: resource name: cloudfoundry.org brief: > @@ -31,7 +31,7 @@ groups: attributes: - ref: cloudfoundry.org.id - ref: cloudfoundry.org.name - - id: cloudfoundry.process + - id: resource.cloudfoundry.process type: resource name: cloudfoundry.process brief: > diff --git a/model/container/resources.yaml b/model/container/resources.yaml index 039faa8616..a3def21acd 100644 --- a/model/container/resources.yaml +++ b/model/container/resources.yaml @@ -1,5 +1,5 @@ groups: - - id: container + - id: resource.container type: resource name: container brief: > diff --git a/model/database/deprecated/metrics-deprecated.yaml b/model/database/deprecated/metrics-deprecated.yaml index 5e6332294f..ebe45355d9 100644 --- a/model/database/deprecated/metrics-deprecated.yaml +++ b/model/database/deprecated/metrics-deprecated.yaml @@ -1,5 +1,5 @@ groups: - - id: metric.db.client.connections.count.deprecated + - id: metric.db.client.connections.usage type: metric metric_name: db.client.connections.usage stability: experimental @@ -13,7 +13,7 @@ groups: - ref: db.client.connections.pool.name requirement_level: required - - id: metric.db.client.connections.idle.max.deprecated + - id: metric.db.client.connections.idle.max type: metric metric_name: db.client.connections.idle.max stability: experimental @@ -25,7 +25,7 @@ groups: - ref: db.client.connections.pool.name requirement_level: required - - id: metric.db.client.connections.idle.min.deprecated + - id: metric.db.client.connections.idle.min type: metric metric_name: db.client.connections.idle.min stability: experimental @@ -37,7 +37,7 @@ groups: - ref: db.client.connections.pool.name requirement_level: required - - id: metric.db.client.connections.max.deprecated + - id: metric.db.client.connections.max type: metric metric_name: db.client.connections.max stability: experimental @@ -49,7 +49,7 @@ groups: - ref: db.client.connections.pool.name requirement_level: required - - id: metric.db.client.connections.pending_requests.deprecated + - id: metric.db.client.connections.pending_requests type: metric metric_name: db.client.connections.pending_requests stability: experimental @@ -61,7 +61,7 @@ groups: - ref: db.client.connections.pool.name requirement_level: required - - id: metric.db.client.connections.timeouts.deprecated + - id: metric.db.client.connections.timeouts type: metric metric_name: db.client.connections.timeouts stability: experimental @@ -73,7 +73,7 @@ groups: - ref: db.client.connections.pool.name requirement_level: required - - id: metric.db.client.connections.create_time.deprecated + - id: metric.db.client.connections.create_time type: metric metric_name: db.client.connections.create_time stability: experimental @@ -85,7 +85,7 @@ groups: - ref: db.client.connections.pool.name requirement_level: required - - id: metric.db.client.connections.wait_time.deprecated + - id: metric.db.client.connections.wait_time type: metric metric_name: db.client.connections.wait_time stability: experimental @@ -97,7 +97,7 @@ groups: - ref: db.client.connections.pool.name requirement_level: required - - id: metric.db.client.connections.use_time.deprecated + - id: metric.db.client.connections.use_time type: metric metric_name: db.client.connections.use_time stability: experimental diff --git a/model/database/spans.yaml b/model/database/spans.yaml index 551b12bed6..33bca315c8 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -75,17 +75,18 @@ groups: requirement_level: conditionally_required: If available. - - id: db + - id: span.db.client type: span stability: experimental brief: This span defines the attributes used to perform database client calls. span_kind: client extends: trace.db.common.full - - id: db.mssql + - id: span.db.mssql.client type: span stability: experimental - extends: db.sql + extends: span.db.sql.client + span_kind: client brief: > Attributes for Microsoft SQL Server attributes: @@ -116,9 +117,10 @@ groups: Microsoft SQL Server does not report SQLSTATE. examples: ["102", "40020"] - - id: db.postgresql + - id: span.db.postgresql.client type: span - extends: db.sql + extends: span.db.sql.client + span_kind: client brief: > Attributes for PostgreSQL attributes: @@ -149,9 +151,10 @@ groups: [PostgreSQL error code](https://www.postgresql.org/docs/current/errcodes-appendix.html). examples: ["08000", "08P01"] - - id: db.mysql + - id: span.db.mysql.client type: span - extends: db.sql + extends: span.db.sql.client + span_kind: client brief: > Attributes for MySQL attributes: @@ -174,9 +177,10 @@ groups: [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html). examples: ["1005", "MY-010016"] - - id: db.mariadb + - id: span.db.mariadb.client type: span - extends: db.sql + extends: span.db.sql.client + span_kind: client brief: > Attributes for MariaDB attributes: @@ -200,8 +204,9 @@ groups: represented as a string. examples: ["1008", "3058"] - - id: db.cassandra + - id: span.db.cassandra.client type: span + span_kind: client stability: experimental extends: trace.db.common.query_and_collection brief: > @@ -234,8 +239,9 @@ groups: brief: > [Cassandra protocol error code](https://github.com/apache/cassandra/blob/cassandra-5.0/doc/native_protocol_v5.spec) represented as a string. examples: ["102", "40020"] - - id: db.hbase + - id: span.db.hbase.client type: span + span_kind: client stability: experimental extends: trace.db.common.minimal brief: > @@ -264,8 +270,9 @@ groups: examples: ["200", "409", "14"] requirement_level: conditionally_required: If response was received. - - id: db.couchdb + - id: span.db.couchdb.client type: span + span_kind: client stability: experimental extends: trace.db.common.minimal brief: > @@ -296,9 +303,10 @@ groups: requirement_level: conditionally_required: If response was received and the HTTP response code is available. - - id: db.redis + - id: span.db.redis.client type: span stability: experimental + span_kind: client extends: attributes.db.client.minimal brief: > Attributes for Redis @@ -359,9 +367,10 @@ groups: - ref: server.port sampling_relevant: true - - id: db.mongodb + - id: span.db.mongodb.client type: span stability: experimental + span_kind: client extends: trace.db.common.minimal brief: > Attributes for MongoDB @@ -393,9 +402,10 @@ groups: conditionally_required: If the operation failed and error code is available. examples: ["36", "11602"] - - id: db.elasticsearch + - id: span.db.elasticsearch.client type: span stability: experimental + span_kind: client extends: trace.db.common.minimal brief: > Attributes for Elasticsearch @@ -448,8 +458,9 @@ groups: examples: ["200", "201", "429"] requirement_level: conditionally_required: If response was received. - - id: db.sql + - id: span.db.sql.client type: span + span_kind: client stability: experimental extends: trace.db.common.query_and_collection brief: > @@ -531,9 +542,10 @@ groups: examples: ["ORA-17027", "1052", "2201B"] requirement_level: conditionally_required: If response has ended with warning or an error. - - id: db.cosmosdb + - id: span.db.cosmosdb.client type: span stability: experimental + span_kind: client extends: trace.db.common.query_and_collection brief: > Attributes for Cosmos DB. diff --git a/model/deployment/resources.yaml b/model/deployment/resources.yaml index 5e40253d2d..18af6c6c66 100644 --- a/model/deployment/resources.yaml +++ b/model/deployment/resources.yaml @@ -1,5 +1,5 @@ groups: - - id: deployment + - id: resource.deployment type: resource name: deployment brief: > diff --git a/model/device/events.yaml b/model/device/events.yaml index 36f4f9885f..fc4a613202 100644 --- a/model/device/events.yaml +++ b/model/device/events.yaml @@ -1,5 +1,5 @@ groups: - - id: device.app.lifecycle + - id: event.device.app.lifecycle stability: experimental type: event name: device.app.lifecycle diff --git a/model/device/resources.yaml b/model/device/resources.yaml index 45b1cd7a49..179e4726f7 100644 --- a/model/device/resources.yaml +++ b/model/device/resources.yaml @@ -1,5 +1,5 @@ groups: - - id: device + - id: resource.device type: resource name: device brief: > diff --git a/model/exceptions/events.yaml b/model/exceptions/events.yaml index 88ff5f3872..10d9691ebe 100644 --- a/model/exceptions/events.yaml +++ b/model/exceptions/events.yaml @@ -1,5 +1,5 @@ groups: - - id: trace-exception + - id: event.exception name: exception stability: stable type: event diff --git a/model/faas/resources.yaml b/model/faas/resources.yaml index 5f9325ebb1..a197e28ea5 100644 --- a/model/faas/resources.yaml +++ b/model/faas/resources.yaml @@ -1,5 +1,5 @@ groups: - - id: faas_resource + - id: resource.faas type: resource name: faas brief: > diff --git a/model/faas/spans.yaml b/model/faas/spans.yaml index 2531347bff..683181502a 100644 --- a/model/faas/spans.yaml +++ b/model/faas/spans.yaml @@ -1,5 +1,5 @@ groups: - - id: faas_span + - id: span.faas type: span brief: > This semantic convention describes an instance of a function that @@ -20,7 +20,7 @@ groups: - ref: faas.invocation_id - ref: cloud.resource_id - - id: faas_span.datasource + - id: span.faas.datasource type: span brief: > Semantic Convention for FaaS triggered as a response to some data @@ -33,7 +33,7 @@ groups: - ref: faas.document.time - ref: faas.document.name - - id: faas_span.timer + - id: span.faas.timer type: span brief: > Semantic Convention for FaaS scheduled to be executed regularly. @@ -41,7 +41,7 @@ groups: - ref: faas.time - ref: faas.cron - - id: faas_span.in + - id: span.faas.server span_kind: server type: span brief: > @@ -61,7 +61,7 @@ groups: nothing to do with the underlying transport used to make the API call to invoke the lambda, which is often HTTP). - - id: faas_span.out + - id: span.faas.client span_kind: client type: span brief: > diff --git a/model/feature-flag/events.yaml b/model/feature-flag/events.yaml index 0248d07cef..bd2cff8829 100644 --- a/model/feature-flag/events.yaml +++ b/model/feature-flag/events.yaml @@ -1,5 +1,5 @@ groups: - - id: feature_flag + - id: event.feature_flag type: event stability: experimental name: feature_flag diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml deleted file mode 100644 index 030c0c11a4..0000000000 --- a/model/feature-flag/logs.yaml +++ /dev/null @@ -1,11 +0,0 @@ -groups: - - id: log-feature_flag - type: event - stability: experimental - name: feature_flag - brief: > - This event describes feature flag evaluation representation on a Log Record. - attributes: - - ref: feature_flag.key - - ref: feature_flag.provider_name - - ref: feature_flag.variant diff --git a/model/gcp/cloud-run-resources.yaml b/model/gcp/cloud-run-resources.yaml index 0fe12bf28d..86c54cb130 100644 --- a/model/gcp/cloud-run-resources.yaml +++ b/model/gcp/cloud-run-resources.yaml @@ -1,5 +1,5 @@ groups: - - id: gcp.cloud_run + - id: resource.gcp.cloud_run type: resource name: gcp.cloud_run brief: > diff --git a/model/gcp/gce-resources.yaml b/model/gcp/gce-resources.yaml index 05cb24e21c..cac414f2b0 100644 --- a/model/gcp/gce-resources.yaml +++ b/model/gcp/gce-resources.yaml @@ -1,5 +1,5 @@ groups: - - id: gcp.gce + - id: resource.gcp.gce type: resource name: gcp.gce brief: > diff --git a/model/gen-ai/events.yaml b/model/gen-ai/events.yaml index 72a4e692f0..e8e3b40967 100644 --- a/model/gen-ai/events.yaml +++ b/model/gen-ai/events.yaml @@ -7,7 +7,7 @@ groups: attributes: - ref: gen_ai.system - - id: gen_ai.system.message + - id: event.gen_ai.system.message name: gen_ai.system.message type: event stability: experimental @@ -15,7 +15,7 @@ groups: This event describes the instructions passed to the GenAI system inside the prompt. extends: gen_ai.common.event.attributes - - id: gen_ai.user.message + - id: event.gen_ai.user.message name: gen_ai.user.message type: event stability: experimental @@ -23,7 +23,7 @@ groups: This event describes the prompt message specified by the user. extends: gen_ai.common.event.attributes - - id: gen_ai.assistant.message + - id: event.gen_ai.assistant.message name: gen_ai.assistant.message type: event stability: experimental @@ -31,7 +31,7 @@ groups: This event describes the assistant message passed to GenAI system or received from it. extends: gen_ai.common.event.attributes - - id: gen_ai.tool.message + - id: event.gen_ai.tool.message name: gen_ai.tool.message type: event stability: experimental @@ -39,7 +39,7 @@ groups: This event describes the tool or function response message. extends: gen_ai.common.event.attributes - - id: gen_ai.choice + - id: event.gen_ai.choice name: gen_ai.choice type: event stability: experimental diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml index a7c8a0ef5e..69252f6673 100644 --- a/model/gen-ai/spans.yaml +++ b/model/gen-ai/spans.yaml @@ -54,9 +54,10 @@ groups: The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. - - id: trace.gen_ai.client.span + - id: span.gen_ai.client type: span stability: experimental + span_kind: client brief: > Describes GenAI operation span. extends: trace.gen_ai.client.common_attributes @@ -70,9 +71,10 @@ groups: - gen_ai.content.prompt - gen_ai.content.completion - - id: trace.gen_ai.openai.client + - id: span.gen_ai.openai.client extends: trace.gen_ai.client.common_attributes stability: experimental + span_kind: client brief: > Describes an OpenAI operation span. attributes: diff --git a/model/graphql/spans.yml b/model/graphql/spans.yml index a14948da0a..7e9e8a494c 100644 --- a/model/graphql/spans.yml +++ b/model/graphql/spans.yml @@ -1,6 +1,7 @@ groups: - - id: graphql + - id: span.graphql.server type: span + span_kind: server brief: > This document defines semantic conventions to apply when instrumenting the GraphQL implementation. They map GraphQL operations to attributes on a Span. diff --git a/model/heroku/resources.yaml b/model/heroku/resources.yaml index cf2e66c233..cfffc3a5b4 100644 --- a/model/heroku/resources.yaml +++ b/model/heroku/resources.yaml @@ -1,9 +1,9 @@ groups: - - id: heroku + - id: resource.heroku type: resource name: heroku brief: > - Heroku dyno metadata + [Heroku dyno metadata](https://devcenter.heroku.com/articles/dyno-metadata) attributes: - ref: heroku.release.creation_timestamp requirement_level: opt_in diff --git a/model/host/resources.yaml b/model/host/resources.yaml index 2954172cd9..088b7c8c2e 100644 --- a/model/host/resources.yaml +++ b/model/host/resources.yaml @@ -1,5 +1,5 @@ groups: - - id: host + - id: resource.host type: resource name: host brief: > @@ -43,7 +43,7 @@ groups: - ref: host.mac requirement_level: opt_in - - id: host.cpu + - id: resource.host.cpu type: resource name: host.cpu brief: > diff --git a/model/http/spans.yaml b/model/http/spans.yaml index 79fa21f22f..2698415ce3 100644 --- a/model/http/spans.yaml +++ b/model/http/spans.yaml @@ -1,5 +1,5 @@ groups: - - id: trace.http.client + - id: span.http.client type: span extends: attributes.http.client span_kind: client @@ -46,7 +46,7 @@ groups: - ref: http.response.body.size requirement_level: opt_in - - id: trace.http.server + - id: span.http.server type: span extends: attributes.http.server span_kind: server diff --git a/model/jvm/deprecated/metrics-deprecated.yaml b/model/jvm/deprecated/metrics-deprecated.yaml index 2641fc1a5c..88c517189b 100644 --- a/model/jvm/deprecated/metrics-deprecated.yaml +++ b/model/jvm/deprecated/metrics-deprecated.yaml @@ -1,5 +1,5 @@ groups: - - id: metric.jvm.buffer.memory.usage.deprecated + - id: metric.jvm.buffer.memory.usage type: metric metric_name: jvm.buffer.memory.usage stability: experimental diff --git a/model/k8s/resources.yaml b/model/k8s/resources.yaml index 50d2e8c254..3e25aff349 100644 --- a/model/k8s/resources.yaml +++ b/model/k8s/resources.yaml @@ -1,5 +1,5 @@ groups: - - id: k8s.cluster + - id: resource.k8s.cluster type: resource name: k8s.cluster brief: > @@ -8,7 +8,7 @@ groups: - ref: k8s.cluster.name - ref: k8s.cluster.uid - - id: k8s.node + - id: resource.k8s.node type: resource name: k8s.node brief: > @@ -17,7 +17,7 @@ groups: - ref: k8s.node.name - ref: k8s.node.uid - - id: k8s.namespace + - id: resource.k8s.namespace type: resource name: k8s.namespace brief: > @@ -25,7 +25,7 @@ groups: attributes: - ref: k8s.namespace.name - - id: k8s.pod + - id: resource.k8s.pod type: resource name: k8s.pod brief: > @@ -37,7 +37,7 @@ groups: - ref: k8s.pod.annotation requirement_level: opt_in - - id: k8s.container + - id: resource.k8s.container type: resource name: k8s.container brief: > @@ -47,7 +47,7 @@ groups: - ref: k8s.container.restart_count - ref: k8s.container.status.last_terminated_reason - - id: k8s.replicaset + - id: resource.k8s.replicaset type: resource name: k8s.replicaset brief: > @@ -56,7 +56,7 @@ groups: - ref: k8s.replicaset.uid - ref: k8s.replicaset.name - - id: k8s.deployment + - id: resource.k8s.deployment type: resource name: k8s.deployment brief: > @@ -65,7 +65,7 @@ groups: - ref: k8s.deployment.uid - ref: k8s.deployment.name - - id: k8s.statefulset + - id: resource.k8s.statefulset type: resource name: k8s.statefulset brief: > @@ -74,7 +74,7 @@ groups: - ref: k8s.statefulset.uid - ref: k8s.statefulset.name - - id: k8s.daemonset + - id: resource.k8s.daemonset type: resource name: k8s.daemonset brief: > @@ -83,7 +83,7 @@ groups: - ref: k8s.daemonset.uid - ref: k8s.daemonset.name - - id: k8s.job + - id: resource.k8s.job type: resource name: k8s.job brief: > @@ -92,7 +92,7 @@ groups: - ref: k8s.job.uid - ref: k8s.job.name - - id: k8s.cronjob + - id: resource.k8s.cronjob type: resource name: k8s.cronjob brief: > diff --git a/model/messaging/spans.yaml b/model/messaging/spans.yaml index 0ad91f4721..1e5dc30413 100644 --- a/model/messaging/spans.yaml +++ b/model/messaging/spans.yaml @@ -28,7 +28,7 @@ groups: # - ref: messaging.system # sampling_relevant: true - - id: messaging + - id: span.messaging type: span stability: experimental brief: > diff --git a/model/os/resources.yaml b/model/os/resources.yaml index da3d241046..fe48ee9c5b 100644 --- a/model/os/resources.yaml +++ b/model/os/resources.yaml @@ -1,5 +1,5 @@ groups: - - id: os + - id: resource.os type: resource name: os brief: > diff --git a/model/otel/resources.yaml b/model/otel/resources.yaml index 2accfa3faf..e07b139778 100644 --- a/model/otel/resources.yaml +++ b/model/otel/resources.yaml @@ -1,5 +1,5 @@ groups: - - id: otel.scope + - id: resource.otel.scope # This should not be a resource, but an attribute group. type: resource name: otel.scope diff --git a/model/process/resources.yaml b/model/process/resources.yaml index f33965fb9b..3c015d607e 100644 --- a/model/process/resources.yaml +++ b/model/process/resources.yaml @@ -1,5 +1,5 @@ groups: - - id: process + - id: resource.process type: resource name: process brief: > @@ -24,7 +24,7 @@ groups: conditionally_required: See [Selecting process attributes](#selecting-process-attributes) for details. - ref: process.owner - - id: process.runtime + - id: resource.process.runtime type: resource name: process.runtime brief: > diff --git a/model/rpc/spans.yaml b/model/rpc/spans.yaml index 07e418d069..ae26b7c256 100644 --- a/model/rpc/spans.yaml +++ b/model/rpc/spans.yaml @@ -1,8 +1,7 @@ groups: - id: rpc - type: span + type: attribute_group brief: 'This document defines semantic conventions for remote procedure calls.' - events: [rpc.message] attributes: - ref: rpc.system requirement_level: required @@ -26,10 +25,12 @@ groups: requirement_level: conditionally_required: if the port is supported by the network transport used for communication. - - id: rpc.client + - id: span.rpc.client type: span brief: 'This document defines semantic conventions for remote procedure call client spans.' extends: rpc + span_kind: client + events: [rpc.message] attributes: - ref: network.peer.address requirement_level: recommended @@ -37,11 +38,12 @@ groups: requirement_level: recommended: If `network.peer.address` is set. - - id: rpc.server + - id: span.rpc.server type: span extends: rpc span_kind: server brief: 'Semantic Convention for RPC server spans' + events: [rpc.message] attributes: - ref: client.address requirement_level: recommended @@ -57,7 +59,7 @@ groups: - ref: network.type requirement_level: recommended - - id: rpc.grpc + - id: span.rpc.grpc type: span extends: rpc brief: 'Tech-specific attributes for gRPC.' @@ -72,7 +74,7 @@ groups: tag: grpc-tech-specific requirement_level: opt_in - - id: rpc.jsonrpc + - id: span.rpc.jsonrpc type: span extends: rpc brief: 'Tech-specific attributes for [JSON RPC](https://www.jsonrpc.org/).' @@ -98,7 +100,7 @@ groups: This is always required for jsonrpc. See the note in the general RPC conventions for more information. - - id: rpc.message + - id: event.rpc.message type: event stability: experimental name: rpc.message @@ -117,7 +119,7 @@ groups: - ref: rpc.message.uncompressed_size requirement_level: recommended - - id: rpc.connect_rpc + - id: span.rpc.connect_rpc type: span extends: rpc brief: 'Tech-specific attributes for Connect RPC.' diff --git a/model/service/resources.yaml b/model/service/resources.yaml index 5e24e377c9..40432c7ece 100644 --- a/model/service/resources.yaml +++ b/model/service/resources.yaml @@ -1,5 +1,5 @@ groups: - - id: service + - id: resource.service type: resource name: service brief: > diff --git a/model/telemetry/resources.yaml b/model/telemetry/resources.yaml index 42511f5cec..6540d2b596 100644 --- a/model/telemetry/resources.yaml +++ b/model/telemetry/resources.yaml @@ -1,6 +1,6 @@ groups: - - id: telemetry.sdk - name: 'telemetry.sdk' + - id: resource.telemetry.sdk + name: telemetry.sdk type: resource stability: stable brief: > @@ -12,7 +12,7 @@ groups: requirement_level: required - ref: telemetry.sdk.version requirement_level: required - - id: telemetry.distro + - id: resource.telemetry.distro name: 'telemetry.distro' type: resource stability: experimental diff --git a/model/webengine/resources.yaml b/model/webengine/resources.yaml index d9026cf2cf..85eac2c52f 100644 --- a/model/webengine/resources.yaml +++ b/model/webengine/resources.yaml @@ -1,5 +1,5 @@ groups: - - id: webengine_resource + - id: resource.webengine type: resource name: webengine brief: > diff --git a/policies/group_stability.rego b/policies/group_stability.rego index c549709bcb..d3cb41718a 100644 --- a/policies/group_stability.rego +++ b/policies/group_stability.rego @@ -11,7 +11,7 @@ deny[group_stability_violation(description, group.id, name)] { # TODO: https://github.com/open-telemetry/semantic-conventions/issues/1514 "metric.kestrel.connection.duration", "metric.kestrel.tls_handshake.duration", # TODO: https://github.com/open-telemetry/semantic-conventions/issues/1519 - "service", + "resource.service", } not exceptions[group.id] diff --git a/policies/yaml_schema.rego b/policies/yaml_schema.rego index c8e40680c6..d8d60471f0 100644 --- a/policies/yaml_schema.rego +++ b/policies/yaml_schema.rego @@ -36,6 +36,18 @@ deny[yaml_schema_violation(description, group.id, name)] { description := sprintf("Metric name '%s' is invalid. Metric name %s'", [name, invalid_name_helper]) } +# checks that metric id matches metric.{metric_name} +deny[yaml_schema_violation(description, group.id, name)] { + group := input.groups[_] + name := group.metric_name + name != null + + expected_id := sprintf("metric.%s", [name]) + expected_id != group.id + + description := sprintf("Metric id '%s' is invalid. Metric id must follow 'metric.{metric_name}' pattern and match '%s'", [group.id, expected_id]) +} + # checks event name format deny[yaml_schema_violation(description, group.id, name)] { group := input.groups[_] @@ -48,6 +60,18 @@ deny[yaml_schema_violation(description, group.id, name)] { description := sprintf("Event name '%s' is invalid. Event name %s'", [name, invalid_name_helper]) } +# checks that event id matches event.{name} +deny[yaml_schema_violation(description, group.id, name)] { + group := input.groups[_] + group.type == "event" + name := group.name + + expected_id := sprintf("event.%s", [name]) + expected_id != group.id + + description := sprintf("Event id '%s' is invalid. Event id must follow 'event.{name}' pattern and match '%s'", [group.id, expected_id]) +} + # checks event.name is not referenced in event attributes deny[yaml_schema_violation(description, group.id, name)] { group := input.groups[_] @@ -80,6 +104,23 @@ deny[yaml_schema_violation(description, group.id, name)] { description := sprintf("Resource name '%s' is invalid. Resource name %s'", [name, invalid_name_helper]) } +# checks that resource group id matches resource.{name} +deny[yaml_schema_violation(description, group.id, name)] { + group := input.groups[_] + group.type == "resource" + + # TODO: remove once https://github.com/open-telemetry/semantic-conventions/pull/1423 is merged + exclusions := {"resource.telemetry.sdk_experimental", "resource.service_experimental"} + not exclusions[group.id] + + name := group.name + + expected_id := sprintf("resource.%s", [name]) + expected_id != group.id + + description := sprintf("Resource id '%s' is invalid. Resource id must follow 'resource.{name}' pattern and match '%s'", [group.id, expected_id]) +} + # checks attribute member id format deny[yaml_schema_violation(description, group.id, attr_name)] { group := input.groups[_] @@ -103,6 +144,30 @@ deny[yaml_schema_violation(description, group.id, "")] { description := sprintf("Group '%s' uses prefix '%s'. All attribute should be fully qualified with their id, prefix is no longer supported.", [group.id, group.prefix]) } +# TODO: remove after span_kind is required https://github.com/open-telemetry/semantic-conventions/issues/1513 +# checks that span id matches span.*. pattern if span_kind is not provided +deny[yaml_schema_violation(description, group.id, "")] { + group := input.groups[_] + group.type == "span" + kind := group.span_kind + + kind == null + not regex.match("^span\\.[a-z0-9_.]+$", group.id) + description := sprintf("Group id '%s' is invalid. Span group 'id' must follow 'span.*' pattern", [group.id]) +} + +# checks that span id matches span.*.{kind} pattern if span_kind is not provided +deny[yaml_schema_violation(description, group.id, "")] { + group := input.groups[_] + group.type == "span" + kind := group.span_kind + + kind != null + pattern := sprintf("^span\\.[a-z0-9_.]+\\.%s$", [kind]) + not regex.match(pattern, group.id) + description := sprintf("Group id '%s' is invalid. Span group 'id' must follow 'span.*.%s' pattern", [group.id, kind]) +} + yaml_schema_violation(description, group, attr) = violation { violation := { "id": description, diff --git a/policies/attribute_name_collisions_test.rego b/policies_test/attribute_name_collisions_test.rego similarity index 100% rename from policies/attribute_name_collisions_test.rego rename to policies_test/attribute_name_collisions_test.rego diff --git a/policies/group_stability_test.rego b/policies_test/group_stability_test.rego similarity index 100% rename from policies/group_stability_test.rego rename to policies_test/group_stability_test.rego diff --git a/policies/yaml_schema_test.rego b/policies_test/yaml_schema_test.rego similarity index 55% rename from policies/yaml_schema_test.rego rename to policies_test/yaml_schema_test.rego index a6d135f9d7..6c5cb4cc89 100644 --- a/policies/yaml_schema_test.rego +++ b/policies_test/yaml_schema_test.rego @@ -18,14 +18,38 @@ test_fails_on_invalid_metric_name if { } } +test_fails_on_invalid_metric_id if { + invalid_ids := [ + "foo.bar", + "metric..foo.bar", + "metric.123", + "metric.foo.bar.deprecated", + ] + every id in invalid_ids { + count(deny) >= 1 with input as {"groups": [{"id": id, "type": "metric", "metric_name": "foo.bar"}]} + } +} + test_fails_on_invalid_event_name if { every name in invalid_names { count(deny) >= 1 with input as {"groups": create_event(name)} } } +test_fails_on_invalid_event_id if { + invalid_ids := [ + "foo.bar", + "event..foo.bar", + "event.123", + "evnt.foo.bar.deprecated", + ] + every id in invalid_ids { + count(deny) >= 1 with input as {"groups": [{"id": id, "type": "event", "name": "foo.bar"}]} + } +} + test_fails_on_referenced_event_name_on_event if { - event := [{ "id": "yaml_schema.test", + event := [{ "id": "event.foo", "type": "event", "name": "foo", "attributes": [{"ref": "event.name"}]}] @@ -39,7 +63,7 @@ test_fails_on_invalid_resource_name if { } test_fails_on_missing_resource_name if { - count(deny) >= 1 with input as {"groups": [{"id": "yaml_schema.test", "type": "resource", "name": null}]} + count(deny) >= 1 with input as {"groups": [{"id": "resource.", "type": "resource", "name": null}]} } test_passes_on_valid_names if { @@ -54,20 +78,45 @@ test_fails_if_prefix_is_present if { count(deny) == 1 with input as {"groups": [{"id": "test", "prefix": "foo"}]} } +test_fails_on_invalid_span_id if { + invalid_ids := [ + "foo.bar", + "span.foo.bar", + "span.foo.bar.client.deprecated", + ] + every id in invalid_ids { + count(deny) >= 1 with input as {"groups": [{"id": id, "type": "span", "span_kind": "client"}]} + } +} + +test_fails_on_invalid_resource_id if { + invalid_ids := [ + "foo.bar", + "resource..foo.bar", + "resource.foo.bar.deprecated", + ] + every id in invalid_ids { + count(deny) >= 1 with input as {"groups": [{"id": id, "type": "resource", "name": "foo.bar"}]} + } +} + create_attribute_group(attr) = json { json := [{"id": "yaml_schema.test", "attributes": [{"id": attr}]}] } create_metric(name) = json { - json := [{"id": "yaml_schema.test", "type": "metric", "metric_name": name}] + id := sprintf("metric.%s", [name]) + json := [{"id": id, "type": "metric", "metric_name": name}] } create_event(name) = json { - json := [{"id": "yaml_schema.test", "type": "event", "name": name}] + id := sprintf("event.%s", [name]) + json := [{"id": id, "type": "event", "name": name}] } create_resource(name) = json { - json := [{"id": "yaml_schema.test", "type": "resource", "name": name}] + id := sprintf("resource.%s", [name]) + json := [{"id": id, "type": "resource", "name": name}] } invalid_names := [ From 3c959946a0dcee57e63843790f0c0c7810f897b0 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 12 Nov 2024 08:14:05 -0800 Subject: [PATCH 08/15] Remove "sampling relevant" from metric sections (#1551) --- docs/database/cosmosdb.md | 5 ----- docs/database/database-metrics.md | 10 ---------- model/database/common.yaml | 2 -- 3 files changed, 17 deletions(-) diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 65e8ccdaec..272bce2ab7 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -381,11 +381,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[9]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -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.cosmosdb.consistency_level` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index a82e7ccbd8..145dff3c29 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -169,11 +169,6 @@ For batch operations, if the individual operations are known to have the same qu Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. This attribute has stability level RELEASE CANDIDATE. -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.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 | @@ -359,11 +354,6 @@ For batch operations, if the individual operations are known to have the same qu Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. This attribute has stability level RELEASE CANDIDATE. -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.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/model/database/common.yaml b/model/database/common.yaml index 5d776a2f28..27d0817220 100644 --- a/model/database/common.yaml +++ b/model/database/common.yaml @@ -50,7 +50,6 @@ groups: requirement_level: conditionally_required: If available - ref: db.namespace - sampling_relevant: true requirement_level: conditionally_required: If available. note: "" # overriding the base note @@ -73,7 +72,6 @@ groups: requirement_level: recommended: if readily available or if instrumentation supports query summarization. - ref: db.collection.name - sampling_relevant: true requirement_level: conditionally_required: > If readily available and if a database call is performed on a single collection. From 62306fc8752dc94ee4bd5cabb9ba387d35309817 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 13 Nov 2024 06:15:13 -0800 Subject: [PATCH 09/15] Generalize `db.query.parameter.` to `db.operation.parameter.` (#1559) Co-authored-by: Liudmila Molkova --- .chloggen/1559.yaml | 22 +++++++++++++++++++ docs/attributes-registry/db.md | 7 +++--- docs/database/cassandra.md | 8 +++---- docs/database/cosmosdb.md | 8 +++---- docs/database/database-spans.md | 8 +++---- docs/database/mariadb.md | 8 +++---- docs/database/mssql.md | 8 +++---- docs/database/mysql.md | 8 +++---- docs/database/postgresql.md | 8 +++---- docs/database/redis.md | 8 +++---- docs/database/sql.md | 8 +++---- docs/non-normative/db-migration.md | 2 +- .../deprecated/registry-deprecated.yaml | 8 +++++++ model/database/registry.yaml | 9 ++++---- model/database/spans.yaml | 8 +++---- 15 files changed, 80 insertions(+), 48 deletions(-) create mode 100644 .chloggen/1559.yaml diff --git a/.chloggen/1559.yaml b/.chloggen/1559.yaml new file mode 100644 index 0000000000..3c4b353889 --- /dev/null +++ b/.chloggen/1559.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: Generalize `db.query.parameter.` to `db.operation.parameter.` + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [ 1559 ] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index bc6f42e7f4..02bb9aede5 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -25,7 +25,7 @@ This group defines the attributes used to describe telemetry in the context of d | `db.namespace` | string | The name of the database, fully qualified within the server address and port. [2] | `customers`; `test.users` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.operation.batch.size` | int | The number of queries included in a batch operation. [3] | `2`; `3`; `4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.operation.name` | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.query.parameter.` | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [5] | `someval`; `55` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.operation.parameter.` | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [5] | `someval`; `55` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.query.summary` | string | Low cardinality representation of a database query text. [6] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.query.text` | string | The database query being executed. [7] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.response.returned_rows` | int | Number of rows returned by the operation. | `10`; `30`; `1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -71,8 +71,8 @@ system specific term if more applicable. This attribute has stability level RELEASE CANDIDATE. -**[5]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. -If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +**[5]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. **[6]:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. @@ -245,6 +245,7 @@ This group defines attributes for Elasticsearch. | `db.mssql.instance_name` | string | Deprecated, SQL Server instance is now populated as a part of `db.namespace` attribute. | `MSSQLSERVER` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, no replacement at this time. | | `db.name` | string | Deprecated, use `db.namespace` instead. | `customers`; `main` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | | `db.operation` | string | Deprecated, use `db.operation.name` instead. | `findAndModify`; `HMSET`; `SELECT` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.operation.name`. | +| `db.query.parameter.` | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. | `someval`; `55` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.operation.parameter`. | | `db.redis.database_index` | int | Deprecated, use `db.namespace` instead. | `0`; `1`; `15` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | | `db.sql.table` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | | `db.statement` | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.query.text`. | diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index b1ac94a8a8..456d6cad79 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -40,7 +40,7 @@ The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend a | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [16] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [17] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [18] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [18] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -111,14 +111,14 @@ Even though parameterized query text can potentially have sensitive data, by usi This attribute has stability level RELEASE CANDIDATE. **[15]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[16]:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. **[17]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[18]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. -If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +**[18]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 272bce2ab7..6e0781ecb1 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -58,7 +58,7 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [12] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [13] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [14] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [15] | `cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -217,7 +217,7 @@ Even though parameterized query text can potentially have sensitive data, by usi This attribute has stability level RELEASE CANDIDATE. **[13]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[14]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. @@ -225,8 +225,8 @@ Parameterized query text SHOULD be collected by default (the query parameter val Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it). Default value is "NS". -**[16]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. -If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 88cd2ea50b..15c27c725e 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -112,7 +112,7 @@ These attributes will usually be the same for all operations performed over the | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [17] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this database system. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [18] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [19] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [19] | `someval`; `55` | `Opt-In` | ![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. This attribute has stability level RELEASE CANDIDATE. @@ -186,15 +186,15 @@ Even though parameterized query text can potentially have sensitive data, by usi This attribute has stability level RELEASE CANDIDATE. **[16]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[17]:** Semantic conventions for individual database systems SHOULD document whether `network.peer.*` attributes are applicable. Network peer address and port are useful when the application interacts with individual database nodes directly. If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. **[18]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[19]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. -If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +**[19]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md index 5df5167326..05b25a8e2d 100644 --- a/docs/database/mariadb.md +++ b/docs/database/mariadb.md @@ -32,7 +32,7 @@ The Semantic Conventions for *MariaDB* extend and override the [Database Semanti | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -126,12 +126,12 @@ Even though parameterized query text can potentially have sensitive data, by usi This attribute has stability level RELEASE CANDIDATE. **[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[15]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[16]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. -If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/database/mssql.md b/docs/database/mssql.md index a2b2f8a313..7ef511e56c 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -32,7 +32,7 @@ The Semantic Conventions for the *Microsoft SQL Server* extend and override the | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -96,12 +96,12 @@ Even though parameterized query text can potentially have sensitive data, by usi This attribute has stability level RELEASE CANDIDATE. **[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[15]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[16]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. -If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/database/mysql.md b/docs/database/mysql.md index 63f2a65692..f9df3f6355 100644 --- a/docs/database/mysql.md +++ b/docs/database/mysql.md @@ -32,7 +32,7 @@ The Semantic Conventions for *MySQL* extend and override the [Database Semantic | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -126,12 +126,12 @@ Even though parameterized query text can potentially have sensitive data, by usi This attribute has stability level RELEASE CANDIDATE. **[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[15]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[16]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. -If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md index b4117a9616..93021ce139 100644 --- a/docs/database/postgresql.md +++ b/docs/database/postgresql.md @@ -32,7 +32,7 @@ The Semantic Conventions for *PostgreSQL* extend and override the [Database Sema | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -133,12 +133,12 @@ Even though parameterized query text can potentially have sensitive data, by usi This attribute has stability level RELEASE CANDIDATE. **[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[15]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[16]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. -If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/database/redis.md b/docs/database/redis.md index ac849ee48c..4c7d84a997 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -31,7 +31,7 @@ The Semantic Conventions for [Redis](https://redis.com/) extend and override the | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [12] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [13] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [14] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [14] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** A connection's currently associated database index may change during its lifetime, e.g. from executing `SELECT `. @@ -79,14 +79,14 @@ This attribute has stability level RELEASE CANDIDATE. **[11]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[12]:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. **[13]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[14]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. -If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +**[14]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/database/sql.md b/docs/database/sql.md index ff4f78af70..6154f8aa32 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -56,7 +56,7 @@ Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic co | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -158,12 +158,12 @@ Even though parameterized query text can potentially have sensitive data, by usi This attribute has stability level RELEASE CANDIDATE. **[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[15]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[16]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. -If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/non-normative/db-migration.md b/docs/non-normative/db-migration.md index eee1011900..596a665a2c 100644 --- a/docs/non-normative/db-migration.md +++ b/docs/non-normative/db-migration.md @@ -51,7 +51,7 @@ to | `db.cosmosdb.container` → `db.collection.name` | | | New: `db.operation.batch.size` | | | New: `db.response.status_code` | | -| New: `db.query.parameter.` | Opt-In | +| New: `db.operation.parameter.` | Opt-In | | New: `error.type` | | diff --git a/model/database/deprecated/registry-deprecated.yaml b/model/database/deprecated/registry-deprecated.yaml index 04bcc26ec3..ce41bced8f 100644 --- a/model/database/deprecated/registry-deprecated.yaml +++ b/model/database/deprecated/registry-deprecated.yaml @@ -36,6 +36,14 @@ groups: deprecated: "Replaced by `db.query.text`." stability: experimental examples: ['SELECT * FROM wuser_table', 'SET mykey "WuValue"'] + - id: db.query.parameter + type: template[string] + brief: > + A query parameter used in `db.query.text`, with `` being the parameter name, + and the attribute value being a string representation of the parameter value. + deprecated: "Replaced by `db.operation.parameter`." + stability: experimental + examples: ["someval", "55"] - id: db.cassandra.table type: string stability: experimental diff --git a/model/database/registry.yaml b/model/database/registry.yaml index c67c035cc2..2913ed4e64 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -87,18 +87,19 @@ groups: "SELECT * FROM wuser_table where username = ?", 'SET mykey ?', ] - - id: db.query.parameter + - id: db.operation.parameter type: template[string] stability: experimental # RELEASE CANDIDATE brief: > - A query parameter used in `db.query.text`, with `` being the parameter name, + A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. note: > - Query parameters should only be captured when `db.query.text` is parameterized with placeholders. - If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. + If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match + up with the parameterized placeholders present in `db.query.text`. + This attribute has stability level RELEASE CANDIDATE. examples: ["someval", "55"] - id: db.query.summary diff --git a/model/database/spans.yaml b/model/database/spans.yaml index 33bca315c8..f4b32c0336 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -32,10 +32,10 @@ groups: Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, - see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). + see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). - ref: db.query.summary sampling_relevant: true - - ref: db.query.parameter + - ref: db.operation.parameter requirement_level: opt_in - ref: db.collection.name sampling_relevant: true @@ -342,7 +342,7 @@ groups: Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, - see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). + see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). note: > For **Redis**, the value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`. @@ -360,7 +360,7 @@ groups: The Redis [simple error](https://redis.io/docs/latest/develop/reference/protocol-spec/#simple-errors) prefix. examples: ["ERR", "WRONGTYPE", "CLUSTERDOWN"] - ref: db.operation.batch.size - - ref: db.query.parameter + - ref: db.operation.parameter requirement_level: opt_in - ref: server.address sampling_relevant: true From 56a2bb7d0e32bb8ddf7c244cb8008ccf56bb64bb Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 13 Nov 2024 06:30:17 -0800 Subject: [PATCH 10/15] Remove redis database index from redis span name (#1565) Co-authored-by: Liudmila Molkova --- .chloggen/1565.yaml | 22 ++++++++++++++++++++++ docs/database/redis.md | 6 ++++++ 2 files changed, 28 insertions(+) create mode 100644 .chloggen/1565.yaml diff --git a/.chloggen/1565.yaml b/.chloggen/1565.yaml new file mode 100644 index 0000000000..f2de83d7f2 --- /dev/null +++ b/.chloggen/1565.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: breaking + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: db + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Remove redis database index from the redis span name. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [ 1449 ] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/database/redis.md b/docs/database/redis.md index 4c7d84a997..6408cd35d8 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -10,6 +10,12 @@ The Semantic Conventions for [Redis](https://redis.com/) extend and override the `db.system` MUST be set to `"redis"` and SHOULD be provided **at span creation time**. +## Span name + +Redis spans SHOULD follow the general [database span name convention](./database-spans.md#name), +except that `db.namespace` SHOULD NOT be used in the span name since it is a numeric value that ends up +looking confusing. + ## Attributes From 441adf4f0ad8770541a3c39713b343e3182132db Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 13 Nov 2024 17:27:19 +0100 Subject: [PATCH 11/15] Bump go.opentelemetry.io/build-tools/chloggen from 0.14.0 to 0.15.0 in /internal/tools (#1558) Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- internal/tools/go.mod | 11 +++++++++-- internal/tools/go.sum | 13 ++----------- 2 files changed, 11 insertions(+), 13 deletions(-) diff --git a/internal/tools/go.mod b/internal/tools/go.mod index 19c93e3b51..075a53d8c9 100644 --- a/internal/tools/go.mod +++ b/internal/tools/go.mod @@ -1,8 +1,15 @@ module github.com/open-telemetry/opentelemetry-specification/internal/tools -go 1.12 +go 1.22 require ( github.com/client9/misspell v0.3.4 - go.opentelemetry.io/build-tools/chloggen v0.14.0 + go.opentelemetry.io/build-tools/chloggen v0.15.0 +) + +require ( + github.com/inconshreveable/mousetrap v1.1.0 // indirect + github.com/spf13/cobra v1.8.1 // indirect + github.com/spf13/pflag v1.0.5 // indirect + gopkg.in/yaml.v3 v3.0.1 // indirect ) diff --git a/internal/tools/go.sum b/internal/tools/go.sum index 0557134bfd..051099d8e8 100644 --- a/internal/tools/go.sum +++ b/internal/tools/go.sum @@ -1,7 +1,6 @@ github.com/client9/misspell v0.3.4 h1:ta993UF76GwbvJcIo3Y68y/M3WxlpEHPWIGDkJYwzJI= github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw= github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= -github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= @@ -13,19 +12,11 @@ github.com/spf13/cobra v1.8.1 h1:e5/vxKd/rZsfSJMUX1agtjeTDf+qv1/JdBF8gg5k9ZM= github.com/spf13/cobra v1.8.1/go.mod h1:wHxEcudfqmLYa8iTfL+OuZPbBZkmvliBWKIezN3kD9Y= github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA= github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= -github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= -github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw= -github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo= -github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA= -github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= -github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU= -github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo= github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg= github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= -go.opentelemetry.io/build-tools/chloggen v0.14.0 h1:qVal1JO6V5xTaQ6b07eBAcc0jyCblk8lfVAJHijwqFk= -go.opentelemetry.io/build-tools/chloggen v0.14.0/go.mod h1:+lbmAIYUT2OewAXITyvPACRxruPm44tNH4k6hIUuasE= +go.opentelemetry.io/build-tools/chloggen v0.15.0 h1:G5UeYUgP6x4QXie0yNs/6TjK9nCuuVXgXeDWE9/cxQQ= +go.opentelemetry.io/build-tools/chloggen v0.15.0/go.mod h1:oovDPiOQS4iruTVH469/68hEYjWC48c8u+qJpWJc8Eg= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= -gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= From e8135d3db0a2d36b6bc919df7cfb68664b103dae Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Fri, 15 Nov 2024 12:39:48 +0800 Subject: [PATCH 12/15] Add known Kestrel connection error types (#1548) Co-authored-by: Chris Ross Co-authored-by: Liudmila Molkova --- .chloggen/1548.yaml | 4 ++ docs/dotnet/dotnet-kestrel-metrics.md | 52 ++++++++++++++++++++++++- model/kestrel/metrics.yaml | 55 +++++++++++++++++++++++++++ 3 files changed, 110 insertions(+), 1 deletion(-) create mode 100644 .chloggen/1548.yaml diff --git a/.chloggen/1548.yaml b/.chloggen/1548.yaml new file mode 100644 index 0000000000..9651a2a115 --- /dev/null +++ b/.chloggen/1548.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: kestrel +note: Add .NET 9 error reasons to Kestrel connection metric. +issues: [1582] diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 73e454c421..f63ace4021 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -116,7 +116,57 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`tls.protocol.version`](/docs/attributes-registry/tls.md) | string | Numeric part of the version parsed from the original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) | `1.2`; `3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** Captures the exception type when a connection fails. +**[1]:** Starting from .NET 9, Kestrel `kestrel.connection.duration` metric reports +the following errors types when a corresponding error occurs: + +| Value | Description | Stability | +|---|---|---| +| `aborted_by_app` | The HTTP/1.1 connection was aborted when app code aborted an HTTP request with `HttpContext.Abort()`. | +| `app_shutdown_timeout` | The connection was aborted during app shutdown. During shutdown, the server stops accepting new connections and HTTP requests, and it is given time for active requests to complete. If the app shutdown timeout is exceeded, all remaining connections are aborted. | +| `closed_critical_stream` | A critical control stream for an HTTP/3 connection was closed. | +| `connection_reset` | The connection was reset while there were active HTTP/2 or HTTP/3 streams on the connection. | +| `error_after_starting_response` | An error such as an unhandled application exception or invalid request body occurred after the response was started, causing an abort of the HTTP/1.1 connection. | +| `error_reading_headers` | An error occurred when decoding HPACK headers in an HTTP/2 `HEADERS` frame. | +| `error_writing_headers` | An error occurred when encoding HPACK headers in an HTTP/2 `HEADERS` frame. | +| `flow_control_queue_size_exceeded` | The connection exceeded the outgoing flow control maximum queue size and was closed with `INTERNAL_ERROR`. This can be caused by an excessive number of HTTP/2 stream resets. For more information, see [Microsoft Security Advisory CVE-2023-44487](https://github.com/dotnet/runtime/issues/93303). | +| `flow_control_window_exceeded` | The client sent more data than allowed by the current flow-control window. | +| `frame_after_stream_close` | An HTTP/2 frame was received on a closed stream. | +| `insufficient_tls_version` | The connection doesn't have TLS 1.2 or greater, as required by HTTP/2. | +| `invalid_body_reader_state` | An error occurred when draining the request body, aborting the HTTP/1.1 connection. This could be caused by app code reading the request body and missing a call to `PipeReader.AdvanceTo` in a finally block. | +| `invalid_data_padding` | An HTTP/2 `HEADER` or `DATA` frame has an invalid amount of padding. | +| `invalid_frame_length` | An HTTP/2 frame was received with an invalid frame payload length. The frame could contain a payload that is not valid for the type, or a `DATA` frame payload does not match the length specified in the frame header. | +| `invalid_handshake` | An invalid HTTP/2 handshake was received. | +| `invalid_http_version` | The connection received an HTTP request with the wrong version. For example, a browser sends an HTTP/1.1 request to a plain-text HTTP/2 connection. | +| `invalid_request_headers` | The HTTP request contains invalid headers. This error can occur in a number of scenarios: a header might not be allowed by the HTTP protocol, such as a pseudo-header in the `HEADERS` frame of an HTTP/2 request. A header could also have an invalid value, such as a non-integer `content-length`, or a header name or value might contain invalid characters. | +| `invalid_request_line` | The first line of an HTTP/1.1 request was invalid, potentially due to invalid content or exceeding the allowed limit. Configured by `KestrelServerLimits.MaxRequestLineSize`. | +| `invalid_settings` | The connection received an HTTP/2 or HTTP/3 `SETTINGS` frame with invalid settings. | +| `invalid_stream_id` | An HTTP/2 stream with an invalid stream ID was received. | +| `invalid_window_update_size` | The server received an HTTP/2 `WINDOW_UPDATE` frame with a zero increment, or an increment that caused a flow-control window to exceed the maximum size. | +| `io_error` | An `IOException` occurred while reading or writing HTTP/2 or HTTP/3 connection data. | +| `keep_alive_timeout` | There was no activity on the connection, and the keep-alive timeout configured by `KestrelServerLimits.KeepAliveTimeout` was exceeded. | +| `max_concurrent_connections_exceeded` | The connection exceeded the maximum concurrent connection limit. Configured by `KestrelServerLimits.MaxConcurrentConnections`. | +| `max_frame_length_exceeded` | The connection received an HTTP/2 frame that exceeded the size limit specified by `Http2Limits.MaxFrameSize`. | +| `max_request_body_size_exceeded` | The HTTP request body exceeded the maximum request body size limit. Configured by `KestrelServerLimits.MaxRequestBodySize`. | +| `max_request_header_count_exceeded` | The HTTP request headers exceeded the maximum count limit. Configured by `KestrelServerLimits.MaxRequestHeaderCount`. | +| `max_request_headers_total_size_exceeded` | The HTTP request headers exceeded the maximum total size limit. Configured by `KestrelServerLimits.MaxRequestHeadersTotalSize`. | +| `min_request_body_data_rate` | Reading the request body timed out due to data arriving too slowly. Configured by `KestrelServerLimits.MinRequestBodyDataRate`. | +| `min_response_data_rate` | Writing the response timed out because the client did not read it at the specified minimum data rate. Configured by `KestrelServerLimits.MinResponseDataRate`. | +| `missing_stream_end` | The connection received an HTTP/2 `HEADERS` frame for trailers without a stream end flag. | +| `output_queue_size_exceeded` | The connection exceeded the output queue size and was closed with `INTERNAL_ERROR`. This can be caused by an excessive number of HTTP/2 stream resets. For more information, see [Microsoft Security Advisory CVE-2023-44487](https://github.com/dotnet/runtime/issues/93303). | +| `request_headers_timeout` | Request headers timed out while waiting for headers to be received after the request started. Configured by `KestrelServerLimits.RequestHeadersTimeout`. | +| `response_content_length_mismatch` | The HTTP response body sent data that didn't match the response's `content-length` header. | +| `server_timeout` | The connection timed out with the `IConnectionTimeoutFeature`. | +| `stream_creation_error` | The HTTP/3 connection received a stream that it wouldn't accept. For example, the client created duplicate control streams. | +| `stream_reset_limit_exceeded` | The connection received an excessive number of HTTP/2 stream resets and was closed with `ENHANCE_YOUR_CALM`. For more information, see [Microsoft Security Advisory CVE-2023-44487](https://github.com/dotnet/runtime/issues/93303). | +| `stream_self_dependency` | The connection received an HTTP/2 frame that caused a frame to depend on itself. | +| `tls_handshake_failed` | An error occurred during the TLS handshake for a connection. Only reported for HTTP/1.1 and HTTP/2 connections. The TLS handshake for HTTP/3 is internal to QUIC transport. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tls_not_supported` | A TLS handshake was received by an endpoint that isn't configured to support TLS. | +| `unexpected_end_of_request_content` | The HTTP/1.1 request body ended before the data specified by the `content-length` header or chunked transfer encoding mechanism was received. | +| `unexpected_frame` | An unexpected HTTP/2 or HTTP/3 frame type was received. The frame type is either unknown, unsupported, or invalid for the current stream state. | +| `unknown_stream` | An HTTP/2 frame was received on an unknown stream. | +| `write_canceled` | The cancellation of a response body write aborted the HTTP/1.1 connection. | + +In other cases, `error.type` contains the fully qualified type name of the exception. **[2]:** The value SHOULD be normalized to lowercase. diff --git a/model/kestrel/metrics.yaml b/model/kestrel/metrics.yaml index 0d1499a34c..ba25995767 100644 --- a/model/kestrel/metrics.yaml +++ b/model/kestrel/metrics.yaml @@ -44,7 +44,62 @@ groups: conditionally_required: if and only if an error has occurred. note: "Captures the exception type when a connection fails." examples: ['System.OperationCanceledException', 'Contoso.MyException'] + # yamllint disable rule:line-length + - ref: error.type + # TODO: move note to yaml once https://github.com/open-telemetry/build-tools/issues/192 is supported + note: | + Starting from .NET 9, Kestrel `kestrel.connection.duration` metric reports + the following errors types when a corresponding error occurs: + + | Value | Description | Stability | + |---|---|---| + | `aborted_by_app` | The HTTP/1.1 connection was aborted when app code aborted an HTTP request with `HttpContext.Abort()`. | + | `app_shutdown_timeout` | The connection was aborted during app shutdown. During shutdown, the server stops accepting new connections and HTTP requests, and it is given time for active requests to complete. If the app shutdown timeout is exceeded, all remaining connections are aborted. | + | `closed_critical_stream` | A critical control stream for an HTTP/3 connection was closed. | + | `connection_reset` | The connection was reset while there were active HTTP/2 or HTTP/3 streams on the connection. | + | `error_after_starting_response` | An error such as an unhandled application exception or invalid request body occurred after the response was started, causing an abort of the HTTP/1.1 connection. | + | `error_reading_headers` | An error occurred when decoding HPACK headers in an HTTP/2 `HEADERS` frame. | + | `error_writing_headers` | An error occurred when encoding HPACK headers in an HTTP/2 `HEADERS` frame. | + | `flow_control_queue_size_exceeded` | The connection exceeded the outgoing flow control maximum queue size and was closed with `INTERNAL_ERROR`. This can be caused by an excessive number of HTTP/2 stream resets. For more information, see [Microsoft Security Advisory CVE-2023-44487](https://github.com/dotnet/runtime/issues/93303). | + | `flow_control_window_exceeded` | The client sent more data than allowed by the current flow-control window. | + | `frame_after_stream_close` | An HTTP/2 frame was received on a closed stream. | + | `insufficient_tls_version` | The connection doesn't have TLS 1.2 or greater, as required by HTTP/2. | + | `invalid_body_reader_state` | An error occurred when draining the request body, aborting the HTTP/1.1 connection. This could be caused by app code reading the request body and missing a call to `PipeReader.AdvanceTo` in a finally block. | + | `invalid_data_padding` | An HTTP/2 `HEADER` or `DATA` frame has an invalid amount of padding. | + | `invalid_frame_length` | An HTTP/2 frame was received with an invalid frame payload length. The frame could contain a payload that is not valid for the type, or a `DATA` frame payload does not match the length specified in the frame header. | + | `invalid_handshake` | An invalid HTTP/2 handshake was received. | + | `invalid_http_version` | The connection received an HTTP request with the wrong version. For example, a browser sends an HTTP/1.1 request to a plain-text HTTP/2 connection. | + | `invalid_request_headers` | The HTTP request contains invalid headers. This error can occur in a number of scenarios: a header might not be allowed by the HTTP protocol, such as a pseudo-header in the `HEADERS` frame of an HTTP/2 request. A header could also have an invalid value, such as a non-integer `content-length`, or a header name or value might contain invalid characters. | + | `invalid_request_line` | The first line of an HTTP/1.1 request was invalid, potentially due to invalid content or exceeding the allowed limit. Configured by `KestrelServerLimits.MaxRequestLineSize`. | + | `invalid_settings` | The connection received an HTTP/2 or HTTP/3 `SETTINGS` frame with invalid settings. | + | `invalid_stream_id` | An HTTP/2 stream with an invalid stream ID was received. | + | `invalid_window_update_size` | The server received an HTTP/2 `WINDOW_UPDATE` frame with a zero increment, or an increment that caused a flow-control window to exceed the maximum size. | + | `io_error` | An `IOException` occurred while reading or writing HTTP/2 or HTTP/3 connection data. | + | `keep_alive_timeout` | There was no activity on the connection, and the keep-alive timeout configured by `KestrelServerLimits.KeepAliveTimeout` was exceeded. | + | `max_concurrent_connections_exceeded` | The connection exceeded the maximum concurrent connection limit. Configured by `KestrelServerLimits.MaxConcurrentConnections`. | + | `max_frame_length_exceeded` | The connection received an HTTP/2 frame that exceeded the size limit specified by `Http2Limits.MaxFrameSize`. | + | `max_request_body_size_exceeded` | The HTTP request body exceeded the maximum request body size limit. Configured by `KestrelServerLimits.MaxRequestBodySize`. | + | `max_request_header_count_exceeded` | The HTTP request headers exceeded the maximum count limit. Configured by `KestrelServerLimits.MaxRequestHeaderCount`. | + | `max_request_headers_total_size_exceeded` | The HTTP request headers exceeded the maximum total size limit. Configured by `KestrelServerLimits.MaxRequestHeadersTotalSize`. | + | `min_request_body_data_rate` | Reading the request body timed out due to data arriving too slowly. Configured by `KestrelServerLimits.MinRequestBodyDataRate`. | + | `min_response_data_rate` | Writing the response timed out because the client did not read it at the specified minimum data rate. Configured by `KestrelServerLimits.MinResponseDataRate`. | + | `missing_stream_end` | The connection received an HTTP/2 `HEADERS` frame for trailers without a stream end flag. | + | `output_queue_size_exceeded` | The connection exceeded the output queue size and was closed with `INTERNAL_ERROR`. This can be caused by an excessive number of HTTP/2 stream resets. For more information, see [Microsoft Security Advisory CVE-2023-44487](https://github.com/dotnet/runtime/issues/93303). | + | `request_headers_timeout` | Request headers timed out while waiting for headers to be received after the request started. Configured by `KestrelServerLimits.RequestHeadersTimeout`. | + | `response_content_length_mismatch` | The HTTP response body sent data that didn't match the response's `content-length` header. | + | `server_timeout` | The connection timed out with the `IConnectionTimeoutFeature`. | + | `stream_creation_error` | The HTTP/3 connection received a stream that it wouldn't accept. For example, the client created duplicate control streams. | + | `stream_reset_limit_exceeded` | The connection received an excessive number of HTTP/2 stream resets and was closed with `ENHANCE_YOUR_CALM`. For more information, see [Microsoft Security Advisory CVE-2023-44487](https://github.com/dotnet/runtime/issues/93303). | + | `stream_self_dependency` | The connection received an HTTP/2 frame that caused a frame to depend on itself. | + | `tls_handshake_failed` | An error occurred during the TLS handshake for a connection. Only reported for HTTP/1.1 and HTTP/2 connections. The TLS handshake for HTTP/3 is internal to QUIC transport. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + | `tls_not_supported` | A TLS handshake was received by an endpoint that isn't configured to support TLS. | + | `unexpected_end_of_request_content` | The HTTP/1.1 request body ended before the data specified by the `content-length` header or chunked transfer encoding mechanism was received. | + | `unexpected_frame` | An unexpected HTTP/2 or HTTP/3 frame type was received. The frame type is either unknown, unsupported, or invalid for the current stream state. | + | `unknown_stream` | An HTTP/2 frame was received on an unknown stream. | + | `write_canceled` | The cancellation of a response body write aborted the HTTP/1.1 connection. | + In other cases, `error.type` contains the fully qualified type name of the exception. + # yamllint enable rule:line-length - id: metric.kestrel.rejected_connections type: metric metric_name: kestrel.rejected_connections From fa564c9f6755a73699398ea44d1e22b0e75e48dd Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Fri, 15 Nov 2024 11:42:26 -0700 Subject: [PATCH 13/15] Feature Flag evaluation event (#1440) Co-authored-by: Liudmila Molkova Co-authored-by: Josh Suereth --- .chloggen/1440.yaml | 6 ++ docs/attributes-registry/feature-flag.md | 38 ++++++-- docs/feature-flags/README.md | 1 - docs/feature-flags/feature-flags-logs.md | 87 +++++++++++++++---- docs/feature-flags/feature-flags-spans.md | 80 ----------------- docs/general/trace.md | 1 - .../deprecated/registry-deprecated.yaml | 12 +++ model/feature-flag/events.yaml | 14 --- model/feature-flag/logs.yaml | 64 ++++++++++++++ model/feature-flag/registry.yaml | 79 +++++++++++++++-- schema-next.yaml | 5 ++ 11 files changed, 260 insertions(+), 127 deletions(-) create mode 100644 .chloggen/1440.yaml delete mode 100644 docs/feature-flags/feature-flags-spans.md create mode 100644 model/feature-flag/deprecated/registry-deprecated.yaml delete mode 100644 model/feature-flag/events.yaml create mode 100644 model/feature-flag/logs.yaml diff --git a/.chloggen/1440.yaml b/.chloggen/1440.yaml new file mode 100644 index 0000000000..f130197287 --- /dev/null +++ b/.chloggen/1440.yaml @@ -0,0 +1,6 @@ +change_type: breaking +component: feature_flag +note: > + Rename `feature_flag` event to `feature_flag.evaluation` event, define new feature flag attributes and provide body definition. + Remove `feature_flag` span event definition in favor of log-based event. +issues: [1440] diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md index 91e0be7a53..de4cd52d50 100644 --- a/docs/attributes-registry/feature-flag.md +++ b/docs/attributes-registry/feature-flag.md @@ -6,21 +6,47 @@ # Feature Flag +- [Feature Flag Attributes](#feature-flag-attributes) +- [Deprecated Feature Flag Attributes](#deprecated-feature-flag-attributes) + ## Feature Flag Attributes This document defines attributes for Feature Flags. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `feature_flag.key` | string | The unique identifier of the feature flag. | `logo-color` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.provider_name` | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.variant` | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.context.id` | string | The unique identifier for the flag evaluation context. For example, the targeting key. | `5157782b-2203-4c80-a857-dbbd5e7761db` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.evaluation.error.message` | string | A message explaining the nature of an error occurring during flag evaluation. | `Flag `header-color` expected type `string` but found type `number`` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.evaluation.reason` | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.key` | string | The lookup key of the feature flag. | `logo-color` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.set.id` | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) to which the feature flag belongs. | `proj-1`; `ab98sgs`; `service1/dev` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.system` | string | Identifies the feature flag provider. | `Flag Manager` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.variant` | string | A semantic identifier for an evaluated flag value. [1] | `red`; `true`; `on` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.version` | string | The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. | `1`; `01ABCDEF` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** A semantic identifier, commonly referred to as a variant, provides a means for referring to a value without including the value itself. This can provide additional context for understanding the meaning behind a value. For example, the variant `red` maybe be used for the value `#c05543`. -A stringified version of the value can be used in situations where a -semantic identifier is unavailable. String representation of the value -should be determined by the implementer. +`feature_flag.evaluation.reason` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `cached` | The resolved value was retrieved from cache. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `default` | The resolved value fell back to a pre-configured value (no dynamic evaluation occurred or dynamic evaluation yielded no result). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `disabled` | The resolved value was the result of the flag being disabled in the management system. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `error` | The resolved value was the result of an error. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `split` | The resolved value was the result of pseudorandom assignment. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `stale` | The resolved value is non-authoritative or possibly out of date | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `static` | The resolved value is static (no dynamic evaluation). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `targeting_match` | The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unknown` | The reason for the resolved value could not be determined. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Deprecated Feature Flag Attributes + +Describes deprecated Feature Flag attributes. + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `feature_flag.provider_name` | string | Deprecated, use `feature_flag.system` instead. | `Flag Manager` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `feature_flag.system`. | diff --git a/docs/feature-flags/README.md b/docs/feature-flags/README.md index 2262031198..1d4a454078 100644 --- a/docs/feature-flags/README.md +++ b/docs/feature-flags/README.md @@ -14,7 +14,6 @@ evaluations in spans and logs. Semantic conventions for feature flags are defined for the following signals: -* [Feature Flags in Spans](feature-flags-spans.md): Semantic Conventions for recording feature flags in *spans*. * [Feature Flags in Logs](feature-flags-logs.md): Semantic Conventions for recording feature flags in *logs*. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 32b2519220..85964d8181 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -11,12 +11,16 @@ a [log record](https://github.com/open-telemetry/opentelemetry-specification/tre [Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/bridge-api.md#emit-a-logrecord). This is useful when a flag is evaluated outside of a transaction context such as when the application loads or on a timer. -To record a flag evaluation as a part of a transaction context, -consider [recording it as a span event](feature-flags-spans.md). -For more information about why it is useful to capture feature flag evaluations, -refer to the [motivation](feature-flags-spans.md#motivation) -section of the trace semantic convention for feature flag evaluations. +## Motivation + +Features flags are commonly used in modern applications to decouple feature releases from deployments. +Many feature flagging tools support the ability to update flag configurations in near real-time from a remote feature flag management service. +They also commonly allow rulesets to be defined that return values based on contextual information. +For example, a feature could be enabled only for a specific subset of users based on context (e.g. users email domain, membership tier, country). + +Since feature flags are dynamic and affect runtime behavior, it's important to collect relevant feature flag telemetry signals. +This can be used to determine the impact a feature has on a request, enabling enhanced observability use cases, such as A/B testing or progressive feature releases. @@ -37,7 +41,7 @@ context. The table below indicates which attributes should be added to the [LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. - + @@ -46,24 +50,75 @@ The table below indicates which attributes should be added to the **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The event name MUST be `feature_flag`. +The event name MUST be `feature_flag.evaluation`. -This event describes feature flag evaluation. +Defines feature flag evaluation as an event. + +A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag value is evaluated, which may happen many times over the course of an application lifecycle. For example, a website A/B testing different animations may evaluate a flag each time a button is clicked. A `feature_flag.evaluation` event is emitted on each evaluation even if the result is the same. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The unique identifier of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.provider_name`](/docs/attributes-registry/feature-flag.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** A semantic identifier, commonly referred to as a variant, provides a means +| [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The lookup key of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | A semantic identifier for an evaluated flag value. [3] | `red`; `true`; `on` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.context.id`](/docs/attributes-registry/feature-flag.md) | string | The unique identifier for the flag evaluation context. For example, the targeting key. | `5157782b-2203-4c80-a857-dbbd5e7761db` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.evaluation.error.message`](/docs/attributes-registry/feature-flag.md) | string | A message explaining the nature of an error occurring during flag evaluation. | `Flag `header-color` expected type `string` but found type `number`` | `Recommended` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.evaluation.reason`](/docs/attributes-registry/feature-flag.md) | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.set.id`](/docs/attributes-registry/feature-flag.md) | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) to which the feature flag belongs. | `proj-1`; `ab98sgs`; `service1/dev` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.system`](/docs/attributes-registry/feature-flag.md) | string | Identifies the feature flag provider. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.version`](/docs/attributes-registry/feature-flag.md) | string | The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. | `1`; `01ABCDEF` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** If one of these values applies, then it MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `flag_not_found` | The flag could not be found. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `invalid_context` | The evaluation context does not meet provider requirements. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `parse_error` | An error was encountered parsing data, such as a flag configuration. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `provider_fatal` | The provider has entered an irrecoverable error state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `provider_not_ready` | The value was resolved before the provider was initialized. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `targeting_key_missing` | The provider requires a targeting key and one was not provided in the evaluation context. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `type_mismatch` | The type of the flag value does not match the expected type. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `general` | The error was for a reason not enumerated above. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[2]:** If and only if an error occurred during flag evaluation. + +**[3]:** A semantic identifier, commonly referred to as a variant, provides a means for referring to a value without including the value itself. This can provide additional context for understanding the meaning behind a value. For example, the variant `red` maybe be used for the value `#c05543`. -A stringified version of the value can be used in situations where a -semantic identifier is unavailable. String representation of the value -should be determined by the implementer. +**[4]:** If feature flag provider supplies a variant or equivalent concept. + +**[5]:** If and only if an error occurred. It's NOT RECOMMENDED to duplicate the value of `error.type` in `feature_flag.evaluation.error.message`. + +`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) | + +`feature_flag.evaluation.reason` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `cached` | The resolved value was retrieved from cache. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `default` | The resolved value fell back to a pre-configured value (no dynamic evaluation occurred or dynamic evaluation yielded no result). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `disabled` | The resolved value was the result of the flag being disabled in the management system. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `error` | The resolved value was the result of an error. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `split` | The resolved value was the result of pseudorandom assignment. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `stale` | The resolved value is non-authoritative or possibly out of date | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `static` | The resolved value is static (no dynamic evaluation). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `targeting_match` | The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unknown` | The reason for the resolved value could not be determined. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**Body fields:** + +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `value` | undefined | The evaluated value of the feature flag. | `#ff0000`; `1`; `true` | `Conditionally Required` [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** If and only if feature flag provider does not supply variant or equivalent concept. Otherwise, `value` should be treated as opt-in. diff --git a/docs/feature-flags/feature-flags-spans.md b/docs/feature-flags/feature-flags-spans.md deleted file mode 100644 index de0ded12fb..0000000000 --- a/docs/feature-flags/feature-flags-spans.md +++ /dev/null @@ -1,80 +0,0 @@ - - -# Semantic Conventions for Feature Flags in Spans - -**Status**: [Experimental][DocumentStatus] - -This document defines semantic conventions for recording dynamic feature flag -evaluations within a transaction as span events. -To record an evaluation outside of a transaction context, consider -[recording it as a log record](feature-flags-logs.md). - - - - - -- [Motivation](#motivation) -- [Overview](#overview) -- [Convention](#convention) - - [Evaluation event](#evaluation-event) - - - -## Motivation - -Features flags are commonly used in modern applications to decouple feature releases from deployments. -Many feature flagging tools support the ability to update flag configurations in near real-time from a remote feature flag management service. -They also commonly allow rulesets to be defined that return values based on contextual information. -For example, a feature could be enabled only for a specific subset of users based on context (e.g. users email domain, membership tier, country). - -Since feature flags are dynamic and affect runtime behavior, it's important to collect relevant feature flag telemetry signals. -This can be used to determine the impact a feature has on a request, enabling enhanced observability use cases, such as A/B testing or progressive feature releases. - -## Overview - -The following semantic convention defines how feature flags can be represented as an `Event` in OpenTelemetry. -The terminology was defined in the [OpenFeature specification](https://docs.openfeature.dev/docs/specification/), which represents an industry consensus. -It's intended to be vendor neutral and provide flexibility for current and future use cases. - -## Convention - -A flag evaluation SHOULD be recorded as an Event on the span during which it occurred. - -### Evaluation event - - - - - - - - -**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) - -The event name MUST be `feature_flag`. - -This event describes feature flag evaluation. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The unique identifier of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.provider_name`](/docs/attributes-registry/feature-flag.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** A semantic identifier, commonly referred to as a variant, provides a means -for referring to a value without including the value itself. This can -provide additional context for understanding the meaning behind a value. -For example, the variant `red` maybe be used for the value `#c05543`. - -A stringified version of the value can be used in situations where a -semantic identifier is unavailable. String representation of the value -should be determined by the implementer. - - - - - - -[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/general/trace.md b/docs/general/trace.md index 09b164af16..565913a31b 100644 --- a/docs/general/trace.md +++ b/docs/general/trace.md @@ -27,7 +27,6 @@ The following semantic conventions for spans are defined: * [Database](/docs/database/database-spans.md): For SQL and NoSQL client call spans. * [Exceptions](/docs/exceptions/exceptions-spans.md): For recording exceptions associated with a span. * [FaaS](/docs/faas/faas-spans.md): For [Function as a Service](https://wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans. -* [Feature Flags](/docs/feature-flags/feature-flags-spans.md): For recording feature flag evaluations associated with a span. * [HTTP](/docs/http/http-spans.md): For HTTP client and server spans. * [Messaging](/docs/messaging/messaging-spans.md): For messaging systems (queues, publish/subscribe, etc.) spans. * [Object Stores](/docs/object-stores/README.md): Semantic Conventions for object stores spans. diff --git a/model/feature-flag/deprecated/registry-deprecated.yaml b/model/feature-flag/deprecated/registry-deprecated.yaml new file mode 100644 index 0000000000..2f3a681454 --- /dev/null +++ b/model/feature-flag/deprecated/registry-deprecated.yaml @@ -0,0 +1,12 @@ +groups: + - id: registry.feature_flag.deprecated + type: attribute_group + display_name: Deprecated Feature Flag Attributes + brief: "Describes deprecated Feature Flag attributes." + attributes: + - id: feature_flag.provider_name + type: string + brief: 'Deprecated, use `feature_flag.system` instead.' + stability: experimental + deprecated: "Replaced by `feature_flag.system`." + examples: ["Flag Manager"] diff --git a/model/feature-flag/events.yaml b/model/feature-flag/events.yaml deleted file mode 100644 index bd2cff8829..0000000000 --- a/model/feature-flag/events.yaml +++ /dev/null @@ -1,14 +0,0 @@ -groups: - - id: event.feature_flag - type: event - stability: experimental - name: feature_flag - brief: > - This event describes feature flag evaluation. - attributes: - - ref: feature_flag.key - requirement_level: required - - ref: feature_flag.provider_name - requirement_level: recommended - - ref: feature_flag.variant - requirement_level: recommended diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml new file mode 100644 index 0000000000..0de7c95577 --- /dev/null +++ b/model/feature-flag/logs.yaml @@ -0,0 +1,64 @@ +groups: + - id: event.feature_flag.evaluation + type: event + name: feature_flag.evaluation + brief: > + Defines feature flag evaluation as an event. + note: > + A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag + value is evaluated, which may happen many times over the course of an + application lifecycle. + For example, a website A/B testing different animations may evaluate a + flag each time a button is clicked. + A `feature_flag.evaluation` event is emitted on each evaluation even if the result is the same. + attributes: + - ref: feature_flag.key + requirement_level: required + - ref: feature_flag.variant + requirement_level: + conditionally_required: If feature flag provider supplies a variant or equivalent concept. + - ref: feature_flag.system + requirement_level: recommended + - ref: feature_flag.context.id + requirement_level: recommended + - ref: feature_flag.version + requirement_level: recommended + - ref: feature_flag.set.id + requirement_level: recommended + - ref: feature_flag.evaluation.reason + requirement_level: recommended + - ref: error.type + examples: ["provider_not_ready", "targeting_key_missing", "provider_fatal", "general"] + requirement_level: + conditionally_required: If and only if an error occurred during flag evaluation. + # TODO: move note to yaml once https://github.com/open-telemetry/build-tools/issues/192 is supported + note: | + If one of these values applies, then it MUST be used; otherwise, a custom value MAY be used. + + | Value | Description | Stability | + |---|---|---| + | `flag_not_found` | The flag could not be found. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + | `invalid_context` | The evaluation context does not meet provider requirements. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + | `parse_error` | An error was encountered parsing data, such as a flag configuration. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + | `provider_fatal` | The provider has entered an irrecoverable error state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + | `provider_not_ready` | The value was resolved before the provider was initialized. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + | `targeting_key_missing` | The provider requires a targeting key and one was not provided in the evaluation context. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + | `type_mismatch` | The type of the flag value does not match the expected type. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + | `general` | The error was for a reason not enumerated above. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + - ref: feature_flag.evaluation.error.message + requirement_level: + recommended: If and only if an error occurred. It's NOT RECOMMENDED to duplicate the value of `error.type` in `feature_flag.evaluation.error.message`. + body: + id: feature_flag.evaluation + type: map + requirement_level: recommended + fields: + - id: value + type: undefined + stability: experimental + brief: The evaluated value of the feature flag. + requirement_level: + conditionally_required: > + If and only if feature flag provider does not supply variant or equivalent concept. + Otherwise, `value` should be treated as opt-in. + examples: ["#ff0000", "1", "true"] diff --git a/model/feature-flag/registry.yaml b/model/feature-flag/registry.yaml index 380ef79d5f..76b1d5fe3c 100644 --- a/model/feature-flag/registry.yaml +++ b/model/feature-flag/registry.yaml @@ -9,26 +9,87 @@ groups: - id: feature_flag.key type: string stability: experimental - brief: The unique identifier of the feature flag. + brief: The lookup key of the feature flag. examples: ["logo-color"] - - id: feature_flag.provider_name + - id: feature_flag.system type: string stability: experimental - brief: The name of the service provider that performs the flag evaluation. + brief: Identifies the feature flag provider. examples: ["Flag Manager"] - id: feature_flag.variant type: string stability: experimental examples: ["red", "true", "on"] brief: > - SHOULD be a semantic identifier for a value. If one is unavailable, a - stringified version of the value can be used. + A semantic identifier for an evaluated flag value. note: |- A semantic identifier, commonly referred to as a variant, provides a means for referring to a value without including the value itself. This can provide additional context for understanding the meaning behind a value. For example, the variant `red` maybe be used for the value `#c05543`. - - A stringified version of the value can be used in situations where a - semantic identifier is unavailable. String representation of the value - should be determined by the implementer. + - id: feature_flag.context.id + type: string + stability: experimental + examples: ["5157782b-2203-4c80-a857-dbbd5e7761db"] + brief: > + The unique identifier for the flag evaluation context. For example, the targeting key. + - id: feature_flag.version + type: string + stability: experimental + examples: ["1", "01ABCDEF"] + brief: > + The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. + - id: feature_flag.set.id + type: string + stability: experimental + examples: ["proj-1", "ab98sgs", "service1/dev"] + brief: > + The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) to which the feature flag belongs. + - id: feature_flag.evaluation.reason + type: + members: + - id: static + value: "static" + brief: The resolved value is static (no dynamic evaluation). + stability: experimental + - id: default + value: "default" + brief: The resolved value fell back to a pre-configured value (no dynamic evaluation occurred or dynamic evaluation yielded no result). + stability: experimental + - id: targeting_match + value: "targeting_match" + brief: The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting. + stability: experimental + - id: split + value: "split" + brief: The resolved value was the result of pseudorandom assignment. + stability: experimental + - id: cached + value: "cached" + brief: The resolved value was retrieved from cache. + stability: experimental + - id: disabled + value: "disabled" + brief: The resolved value was the result of the flag being disabled in the management system. + stability: experimental + - id: unknown + value: "unknown" + brief: The reason for the resolved value could not be determined. + stability: experimental + - id: stale + value: "stale" + brief: The resolved value is non-authoritative or possibly out of date + stability: experimental + - id: error + value: "error" + brief: The resolved value was the result of an error. + stability: experimental + stability: experimental + examples: ["static", "targeting_match", "error", "default"] + brief: > + The reason code which shows how a feature flag value was determined. + - id: feature_flag.evaluation.error.message + type: string + stability: experimental + examples: ["Flag `header-color` expected type `string` but found type `number`"] + brief: A message explaining the nature of an error occurring during flag evaluation. diff --git a/schema-next.yaml b/schema-next.yaml index 5439843483..50afab2b96 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -16,6 +16,11 @@ versions: vcs.repository.ref.name: vcs.ref.head.name vcs.repository.ref.revision: vcs.ref.head.revision vcs.repository.ref.type: vcs.ref.head.type + # https://github.com/open-telemetry/semantic-conventions/pull/1440 + - rename_attributes: + attribute_map: + feature_flag.provider_name: feature_flag.system + metrics: changes: # https://github.com/open-telemetry/semantic-conventions/pull/1492 From 50ad22e026b4291425a4ae77f65c6eea1548c080 Mon Sep 17 00:00:00 2001 From: Braydon Kains <93549768+braydonk@users.noreply.github.com> Date: Sat, 16 Nov 2024 11:20:34 -0700 Subject: [PATCH 14/15] process: change process.uptime instrument to gauge (#1585) --- .chloggen/process_uptime.yaml | 22 ++++++++++++++++++++++ docs/system/process-metrics.md | 5 +++-- model/process/metrics.yaml | 6 ++++-- 3 files changed, 29 insertions(+), 4 deletions(-) create mode 100644 .chloggen/process_uptime.yaml diff --git a/.chloggen/process_uptime.yaml b/.chloggen/process_uptime.yaml new file mode 100644 index 0000000000..3cbb447101 --- /dev/null +++ b/.chloggen/process_uptime.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: process + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Change process.uptime instrument to a gauge. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1518] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index c08e068e41..3198bef947 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -341,9 +341,10 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `process.uptime` | Counter | `s` | The time the process has been running. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.uptime` | Gauge | `s` | The time the process has been running. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** Instrumentations SHOULD use counter with type `double` and measure uptime with at least millisecond precision +**[1]:** Instrumentations SHOULD use a gauge with type `double` and measure uptime in seconds as a floating point number with the highest precision available. +The actual accuracy would depend on the instrumentation and operating system. diff --git a/model/process/metrics.yaml b/model/process/metrics.yaml index 9df5139e51..01552e2487 100644 --- a/model/process/metrics.yaml +++ b/model/process/metrics.yaml @@ -108,6 +108,8 @@ groups: metric_name: process.uptime stability: experimental brief: "The time the process has been running." - instrument: counter + note: | + Instrumentations SHOULD use a gauge with type `double` and measure uptime in seconds as a floating point number with the highest precision available. + The actual accuracy would depend on the instrumentation and operating system. + instrument: gauge unit: "s" - note: "Instrumentations SHOULD use counter with type `double` and measure uptime with at least millisecond precision" From c1a0a2d508bf71819a2992851e2bd50b2e93542d Mon Sep 17 00:00:00 2001 From: Guangya Liu Date: Sat, 16 Nov 2024 13:23:03 -0500 Subject: [PATCH 15/15] [chore] Fixed a dead link for machine id man page (#1584) Co-authored-by: Liudmila Molkova --- docs/attributes-registry/service.md | 2 +- docs/resource/README.md | 2 +- model/service/registry.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/attributes-registry/service.md b/docs/attributes-registry/service.md index 88ecebc591..6330270636 100644 --- a/docs/attributes-registry/service.md +++ b/docs/attributes-registry/service.md @@ -29,7 +29,7 @@ SHOULD use the following UUID as the namespace: `4d63009a-8d0f-11ee-aad7-4c796ed UUIDs are typically recommended, as only an opaque value for the purposes of identifying a service instance is needed. Similar to what can be seen in the man page for the -[`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/machine-id.html) file, the underlying +[`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/latest/machine-id.html) file, the underlying data, such as pod name and namespace should be treated as confidential, being the user's choice to expose it or not via another resource attribute. diff --git a/docs/resource/README.md b/docs/resource/README.md index ec6365d9e5..2ae0e3520c 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -107,7 +107,7 @@ SHOULD use the following UUID as the namespace: `4d63009a-8d0f-11ee-aad7-4c796ed UUIDs are typically recommended, as only an opaque value for the purposes of identifying a service instance is needed. Similar to what can be seen in the man page for the -[`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/machine-id.html) file, the underlying +[`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/latest/machine-id.html) file, the underlying data, such as pod name and namespace should be treated as confidential, being the user's choice to expose it or not via another resource attribute. diff --git a/model/service/registry.yaml b/model/service/registry.yaml index b2ee398c26..dfb4aef3f5 100644 --- a/model/service/registry.yaml +++ b/model/service/registry.yaml @@ -54,7 +54,7 @@ groups: UUIDs are typically recommended, as only an opaque value for the purposes of identifying a service instance is needed. Similar to what can be seen in the man page for the - [`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/machine-id.html) file, the underlying + [`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/latest/machine-id.html) file, the underlying data, such as pod name and namespace should be treated as confidential, being the user's choice to expose it or not via another resource attribute.