From ad05f1d8d319471e23f9bc2d8afbf3e0f046b873 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 25 Jun 2024 04:40:10 -0700 Subject: [PATCH 01/23] Clarify db.query.parameter is string representation (#1165) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/1165.yaml | 22 ++++++++++++++++++++++ docs/attributes-registry/db.md | 2 +- docs/database/cassandra.md | 2 +- docs/database/cosmosdb.md | 2 +- docs/database/database-spans.md | 2 +- docs/database/mssql.md | 2 +- docs/database/redis.md | 2 +- docs/database/sql.md | 2 +- model/registry/db.yaml | 4 ++-- 9 files changed, 31 insertions(+), 9 deletions(-) create mode 100644 .chloggen/1165.yaml diff --git a/.chloggen/1165.yaml b/.chloggen/1165.yaml new file mode 100644 index 0000000000..76e5ed376f --- /dev/null +++ b/.chloggen/1165.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: db + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Clarify that `db.query.parameter.` is string representation of the parameter value + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [ 1165 ] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index a3a6cb7e41..db78b93f6b 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](/docs/database/database-spans.md#batch-operations). [3] | `2`; `3`; `4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.operation.name` | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.query.parameter.` | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [5] | `someval`; `55` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.query.parameter.` | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [5] | `someval`; `55` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.query.text` | string | The database query being executed. [6] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.system` | string | The database management system (DBMS) product as identified by the client instrumentation. [7] | `other_sql`; `adabas`; `cache` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index cf9eae8aca..fec15f7cf0 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -38,7 +38,7 @@ described on this page. | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [11] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [13] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [13] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 5256694f2c..6fa48db887 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -41,7 +41,7 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [7] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [10] | `cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [11] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [11] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 23e0742623..88093233d8 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -100,7 +100,7 @@ These attributes will usually be the same for all operations performed over the | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [12] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this database system. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [13] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [14] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [14] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge. diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 6d03232088..6962223af7 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -30,7 +30,7 @@ described on this page. | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Conditionally Required` [8] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. diff --git a/docs/database/redis.md b/docs/database/redis.md index 9d1b5ef057..bbe41a21c2 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -31,7 +31,7 @@ described on this page. | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [9] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [11] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [11] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** The database index for current connection can be changed by the application dynamically. Instrumentations MAY use the initial database index provided in the connection string and keep track of the currently selected database to capture the `db.namespace`. Instrumentations SHOULD NOT set this attribute if capturing it would require additional network calls to Redis. diff --git a/docs/database/sql.md b/docs/database/sql.md index 115ec29eaa..524c5878bd 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -52,7 +52,7 @@ Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic co | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Conditionally Required` [8] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. diff --git a/model/registry/db.yaml b/model/registry/db.yaml index f1efd77a5f..c94ac32e0f 100644 --- a/model/registry/db.yaml +++ b/model/registry/db.yaml @@ -68,8 +68,8 @@ groups: type: template[string] stability: experimental brief: > - The query parameters used in `db.query.text`, with `` being the parameter name, - and the attribute value being the parameter value. + A query parameter used in `db.query.text`, with `` being the parameter name, + and the attribute value being a string representation of the parameter value. note: > Query parameters should only be captured when `db.query.text` is parameterized with placeholders. From db1b84d45d09d0c3de67aa4006d2415a994dca07 Mon Sep 17 00:00:00 2001 From: Chris Mark Date: Wed, 26 Jun 2024 10:46:38 +0300 Subject: [PATCH 02/23] Merge *.cpu.state attributes to a common cpu.mode attribute (#1026) Signed-off-by: ChrsMark Co-authored-by: Alexandra Konrad Co-authored-by: Liudmila Molkova Co-authored-by: Braydon Kains <93549768+braydonk@users.noreply.github.com> Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/merge_cpu_states.yaml | 22 ++++++++++++ .github/ISSUE_TEMPLATE/bug_report.yaml | 1 + .github/ISSUE_TEMPLATE/change_proposal.yaml | 1 + .github/ISSUE_TEMPLATE/new-conventions.yaml | 1 + docs/attributes-registry/README.md | 1 + docs/attributes-registry/container.md | 18 +++++----- docs/attributes-registry/cpu.md | 28 +++++++++++++++ docs/attributes-registry/process.md | 12 +++---- docs/attributes-registry/system.md | 26 +++++++------- docs/system/container-metrics.md | 19 ++++++++--- docs/system/process-metrics.md | 30 ++++++++++++---- docs/system/system-metrics.md | 18 +++++++--- model/metrics/container.yaml | 5 +-- model/metrics/process-metrics.yaml | 14 ++++---- model/metrics/system-metrics.yaml | 10 +++--- model/registry/container.yaml | 19 ----------- model/registry/cpu.yaml | 38 +++++++++++++++++++++ model/registry/deprecated/container.yaml | 20 +++++++++++ model/registry/deprecated/process.yaml | 21 ++++++++++++ model/registry/deprecated/system.yaml | 29 ++++++++++++++++ model/registry/process.yaml | 23 ------------- model/registry/system.yaml | 28 --------------- schema-next.yaml | 13 ++++++- templates/registry/markdown/weaver.yaml | 1 + 24 files changed, 272 insertions(+), 126 deletions(-) create mode 100755 .chloggen/merge_cpu_states.yaml create mode 100644 docs/attributes-registry/cpu.md create mode 100644 model/registry/cpu.yaml create mode 100644 model/registry/deprecated/process.yaml diff --git a/.chloggen/merge_cpu_states.yaml b/.chloggen/merge_cpu_states.yaml new file mode 100755 index 0000000000..54ea54c032 --- /dev/null +++ b/.chloggen/merge_cpu_states.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: breaking + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: system + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Rename `process.cpu.state`, `container.cpu.state`, and `system.cpu.state` attributes into a common `cpu.mode` attribute + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [840] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 33cf248bb7..f4add087f9 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -28,6 +28,7 @@ body: - area:cloudevents - area:code - area:container + - area:cpu - area:db - area:deployment - area:destination diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 4429b696e6..e5c7532f76 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -21,6 +21,7 @@ body: - area:cloudevents - area:code - area:container + - area:cpu - area:db - area:deployment - area:destination diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index 1a504ea5ce..b4099a42cb 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -30,6 +30,7 @@ body: - area:cloudevents - area:code - area:container + - area:cpu - area:db - area:deployment - area:destination diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 2aa1b98447..97eab1087b 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -40,6 +40,7 @@ Currently, the following namespaces exist: - [CloudEvents](cloudevents.md) - [Code](code.md) - [Container](container.md) +- [CPU](cpu.md) - [Db](db.md) - [Deployment](deployment.md) - [Destination](destination.md) diff --git a/docs/attributes-registry/container.md b/docs/attributes-registry/container.md index 12ae8414bf..fdca43d789 100644 --- a/docs/attributes-registry/container.md +++ b/docs/attributes-registry/container.md @@ -18,7 +18,6 @@ A container instance. | `container.command` | string | The command used to run the container (i.e. the command name). [1] | `otelcontribcol` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `container.command_args` | string[] | All the command arguments (including the command/executable itself) run by the container. [2] | `["otelcontribcol, --config, config.yaml"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `container.command_line` | string | The full command run by the container as a single string representing the full command. [2] | `otelcontribcol --config config.yaml` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `container.cpu.state` | string | The CPU state for this data point. | `user`; `kernel` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `container.id` | string | Container ID. Usually a UUID, as for example used to [identify Docker containers](https://docs.docker.com/engine/reference/run/#container-identification). The UUID might be abbreviated. | `a3bf90e006b2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `container.image.id` | string | Runtime specific image identifier. Usually a hash algorithm followed by a UUID. [2] | `sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `container.image.name` | string | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -36,18 +35,19 @@ The ID is assigned by the container runtime and can vary in different environmen **[3]:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field. -`container.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -| -------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `kernel` | When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `system` | When CPU is used by the system (host OS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `user` | When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - ## Container Deprecated Attributes Describes deprecated container attributes. | Attribute | Type | Description | Examples | Stability | | ------------------------ | ------ | ------------------------------------------ | --------------------------- | --------------------------------------------------------------------------------------------- | +| `container.cpu.state` | string | Deprecated, use `cpu.mode` instead. | `user`; `kernel` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `cpu.mode` | | `container.labels.` | string | Deprecated, use `container.label` instead. | `container.label.app=nginx` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `container.label`. | + +`container.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `kernel` | When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system` | When CPU is used by the system (host OS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `user` | When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/cpu.md b/docs/attributes-registry/cpu.md new file mode 100644 index 0000000000..2e405a8a83 --- /dev/null +++ b/docs/attributes-registry/cpu.md @@ -0,0 +1,28 @@ + + + + + +# CPU + +## CPU Attributes + +Attributes specific to a cpu instance. + +| Attribute | Type | Description | Examples | Stability | +| ---------- | ------ | ------------------- | ---------------- | ---------------------------------------------------------------- | +| `cpu.mode` | string | The mode of the CPU | `user`; `system` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`cpu.mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ----------- | ----------- | ---------------------------------------------------------------- | +| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `kernel` | kernel | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/process.md b/docs/attributes-registry/process.md index 2e525794c2..6522b0ace3 100644 --- a/docs/attributes-registry/process.md +++ b/docs/attributes-registry/process.md @@ -7,7 +7,7 @@ # Process - [Process](#process-attributes) -- [Process Cpu](#process-cpu-attributes) +- [Process Deprecated](#process-deprecated-attributes) ## Process Attributes @@ -58,13 +58,13 @@ An operating system process. | `major` | major | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `minor` | minor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Process Cpu Attributes +## Process Deprecated Attributes -Attributes for process CPU +Deprecated process attributes. -| Attribute | Type | Description | Examples | Stability | -| ------------------- | ------ | ----------------------------- | ------------------------ | ---------------------------------------------------------------- | -| `process.cpu.state` | string | The CPU state of the process. | `system`; `user`; `wait` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| ------------------- | ------ | ----------------------------------- | ------------------------ | ------------------------------------------------------------------------------------- | +| `process.cpu.state` | string | Deprecated, use `cpu.mode` instead. | `system`; `user`; `wait` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `cpu.mode` | `process.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. diff --git a/docs/attributes-registry/system.md b/docs/attributes-registry/system.md index de49928773..c504f989f9 100644 --- a/docs/attributes-registry/system.md +++ b/docs/attributes-registry/system.md @@ -23,14 +23,22 @@ Describes System attributes | --------------- | ------ | --------------------- | -------------- | ---------------------------------------------------------------- | | `system.device` | string | The device identifier | `(identifier)` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## System Cpu Attributes +## System CPU Attributes Describes System CPU attributes -| Attribute | Type | Description | Examples | Stability | -| --------------------------- | ------ | ------------------------------- | ------------------- | ---------------------------------------------------------------- | -| `system.cpu.logical_number` | int | The logical CPU number [0..n-1] | `1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `system.cpu.state` | string | The state of the CPU | `idle`; `interrupt` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| --------------------------- | ---- | ------------------------------- | -------- | ---------------------------------------------------------------- | +| `system.cpu.logical_number` | int | The logical CPU number [0..n-1] | `1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## System Deprecated Attributes + +Deprecated system attributes. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------- | ------ | ------------------------------------------------ | ------------------- | --------------------------------------------------------------------------------------------------- | +| `system.cpu.state` | string | Deprecated, use `cpu.mode` instead. | `idle`; `interrupt` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `cpu.mode` | +| `system.processes.status` | string | Deprecated, use `system.process.status` instead. | `running` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `system.process.status`. | `system.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. @@ -44,14 +52,6 @@ Describes System CPU attributes | `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## System Deprecated Attributes - -Deprecated system attributes. - -| Attribute | Type | Description | Examples | Stability | -| ------------------------- | ------ | ------------------------------------------------ | --------- | --------------------------------------------------------------------------------------------------- | -| `system.processes.status` | string | Deprecated, use `system.process.status` instead. | `running` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `system.process.status`. | - `system.processes.status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/system/container-metrics.md b/docs/system/container-metrics.md index 5449a117d0..b0fb198f21 100644 --- a/docs/system/container-metrics.md +++ b/docs/system/container-metrics.md @@ -42,15 +42,24 @@ This metric is [opt-in][MetricOptIn]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`container.cpu.state`](/docs/attributes-registry/container.md) | string | The CPU state for this data point. A container SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `user`; `kernel` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A container's CPU metric SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`container.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +**[1]:** Following states SHOULD be used: `user`, `system`, `kernel` + + + +`cpu.mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| -| `kernel` | When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `system` | When CPU is used by the system (host OS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `user` | When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `kernel` | kernel | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index 5b40717462..892382e40f 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -75,15 +75,24 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`process.cpu.state`](/docs/attributes-registry/process.md) | string | A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `system`; `user`; `wait` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | A process SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`process.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +**[1]:** Following states SHOULD be used: `user`, `system`, `wait` + + + +`cpu.mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| +| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `kernel` | kernel | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `wait` | wait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -122,15 +131,24 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`process.cpu.state`](/docs/attributes-registry/process.md) | string | A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `system`; `user`; `wait` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | A process SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Following states SHOULD be used: `user`, `system`, `wait` + + -`process.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +`cpu.mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| +| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `kernel` | kernel | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `wait` | wait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 70a9c543af..cd01009e28 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -104,16 +104,21 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| +| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A system's CPU SHOULD be characterized *either* by data points with no `mode` labels, *or only* data points with `mode` labels. [1] | `user`; `system` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`system.cpu.logical_number`](/docs/attributes-registry/system.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`system.cpu.state`](/docs/attributes-registry/system.md) | string | The CPU state for this data point. A system's CPU SHOULD be characterized *either* by data points with no `state` labels, *or only* data points with `state` labels. | `idle`; `interrupt` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`system.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +**[1]:** Following states SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal` + + + +`cpu.mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| | `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `kernel` | kernel | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -156,16 +161,21 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| +| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A system's CPU SHOULD be characterized *either* by data points with no `mode` labels, *or only* data points with `mode` labels. [1] | `user`; `system` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`system.cpu.logical_number`](/docs/attributes-registry/system.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`system.cpu.state`](/docs/attributes-registry/system.md) | string | The CPU state for this data point. A system's CPU SHOULD be characterized *either* by data points with no `state` labels, *or only* data points with `state` labels. | `idle`; `interrupt` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`system.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +**[1]:** Following modes SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal` + + + +`cpu.mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| | `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `kernel` | kernel | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/metrics/container.yaml b/model/metrics/container.yaml index f0e15ed596..94adad2921 100644 --- a/model/metrics/container.yaml +++ b/model/metrics/container.yaml @@ -10,8 +10,9 @@ groups: instrument: counter unit: "s" attributes: - - ref: container.cpu.state - brief: "The CPU state for this data point. A container SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels." + - ref: cpu.mode + brief: "The CPU mode for this data point. A container's CPU metric SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels." + note: "Following states SHOULD be used: `user`, `system`, `kernel`" requirement_level: opt_in # container.memory.* metrics and attribute group diff --git a/model/metrics/process-metrics.yaml b/model/metrics/process-metrics.yaml index 3941cdc56d..86d224d543 100644 --- a/model/metrics/process-metrics.yaml +++ b/model/metrics/process-metrics.yaml @@ -7,10 +7,11 @@ groups: instrument: counter unit: "s" attributes: - - ref: process.cpu.state + - ref: cpu.mode brief: > - A process SHOULD be characterized _either_ by data points with no `state` - labels, _or only_ data points with `state` labels. + A process SHOULD be characterized _either_ by data points with no `mode` + labels, _or only_ data points with `mode` labels. + note: "Following states SHOULD be used: `user`, `system`, `wait`" - id: metric.process.cpu.utilization type: metric @@ -22,10 +23,11 @@ groups: instrument: gauge unit: "1" attributes: - - ref: process.cpu.state + - ref: cpu.mode brief: > - A process SHOULD be characterized _either_ by data points with no `state` - labels, _or only_ data points with `state` labels. + A process SHOULD be characterized _either_ by data points with no `mode` + labels, _or only_ data points with `mode` labels. + note: "Following states SHOULD be used: `user`, `system`, `wait`" - id: metric.process.memory.usage type: metric diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml index 1b7a2cf28e..25e2d06665 100644 --- a/model/metrics/system-metrics.yaml +++ b/model/metrics/system-metrics.yaml @@ -8,8 +8,9 @@ groups: instrument: counter unit: "s" attributes: - - ref: system.cpu.state - brief: "The CPU state for this data point. A system's CPU SHOULD be characterized *either* by data points with no `state` labels, *or only* data points with `state` labels." + - ref: cpu.mode + brief: "The CPU mode for this data point. A system's CPU SHOULD be characterized *either* by data points with no `mode` labels, *or only* data points with `mode` labels." + note: "Following states SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`" - ref: system.cpu.logical_number - id: metric.system.cpu.utilization @@ -20,8 +21,9 @@ groups: instrument: gauge unit: "1" attributes: - - ref: system.cpu.state - brief: "The CPU state for this data point. A system's CPU SHOULD be characterized *either* by data points with no `state` labels, *or only* data points with `state` labels." + - ref: cpu.mode + brief: "The CPU mode for this data point. A system's CPU SHOULD be characterized *either* by data points with no `mode` labels, *or only* data points with `mode` labels." + note: "Following modes SHOULD be used: `user`, `system`, `nice`, `idle`, `iowait`, `interrupt`, `steal`" - ref: system.cpu.logical_number - id: metric.system.cpu.frequency diff --git a/model/registry/container.yaml b/model/registry/container.yaml index b2ff38239f..60348628b4 100644 --- a/model/registry/container.yaml +++ b/model/registry/container.yaml @@ -95,22 +95,3 @@ groups: brief: > Container labels, `` being the label name, the value being the label value. examples: [ 'container.label.app=nginx' ] - - id: cpu.state - brief: "The CPU state for this data point." - type: - allow_custom_values: true - members: - - id: user - value: 'user' - brief: "When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows)." - stability: experimental - - id: system - value: 'system' - brief: "When CPU is used by the system (host OS)" - stability: experimental - - id: kernel - value: 'kernel' - brief: "When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows)." - stability: experimental - stability: experimental - examples: ["user", "kernel"] diff --git a/model/registry/cpu.yaml b/model/registry/cpu.yaml new file mode 100644 index 0000000000..43fb145a38 --- /dev/null +++ b/model/registry/cpu.yaml @@ -0,0 +1,38 @@ +groups: + - id: registry.cpu + prefix: cpu + type: attribute_group + brief: Attributes specific to a cpu instance. + attributes: + - id: mode + brief: "The mode of the CPU" + type: + allow_custom_values: true + # TODO: Fix how enum members are used in semantic conventions after https://github.com/open-telemetry/build-tools/issues/192 is merged + members: + - id: user + value: 'user' + stability: experimental + - id: system + value: 'system' + stability: experimental + - id: nice + value: 'nice' + stability: experimental + - id: idle + value: 'idle' + stability: experimental + - id: iowait + value: 'iowait' + stability: experimental + - id: interrupt + value: 'interrupt' + stability: experimental + - id: steal + value: 'steal' + stability: experimental + - id: kernel + value: 'kernel' + stability: experimental + stability: experimental + examples: [ "user", "system" ] diff --git a/model/registry/deprecated/container.yaml b/model/registry/deprecated/container.yaml index 77f3466f02..63e69621dd 100644 --- a/model/registry/deprecated/container.yaml +++ b/model/registry/deprecated/container.yaml @@ -9,3 +9,23 @@ groups: brief: "Deprecated, use `container.label` instead." stability: experimental deprecated: "Replaced by `container.label`." + - id: container.cpu.state + brief: "Deprecated, use `cpu.mode` instead." + type: + allow_custom_values: true + members: + - id: user + value: 'user' + brief: "When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows)." + stability: experimental + - id: system + value: 'system' + brief: "When CPU is used by the system (host OS)" + stability: experimental + - id: kernel + value: 'kernel' + brief: "When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows)." + stability: experimental + stability: experimental + deprecated: 'Replaced by `cpu.mode`' + examples: [ "user", "kernel" ] diff --git a/model/registry/deprecated/process.yaml b/model/registry/deprecated/process.yaml new file mode 100644 index 0000000000..33c5adb0cb --- /dev/null +++ b/model/registry/deprecated/process.yaml @@ -0,0 +1,21 @@ +groups: + - id: registry.process.deprecated + type: attribute_group + brief: "Deprecated process attributes." + attributes: + - id: process.cpu.state + brief: "Deprecated, use `cpu.mode` instead." + deprecated: 'Replaced by `cpu.mode`' + type: + allow_custom_values: true + members: + - id: system + value: 'system' + stability: experimental + - id: user + value: 'user' + stability: experimental + - id: wait + value: 'wait' + stability: experimental + stability: experimental diff --git a/model/registry/deprecated/system.yaml b/model/registry/deprecated/system.yaml index 700023ab57..d220a501b7 100644 --- a/model/registry/deprecated/system.yaml +++ b/model/registry/deprecated/system.yaml @@ -23,3 +23,32 @@ groups: deprecated: "Replaced by `system.process.status`." stability: experimental examples: ["running"] + - id: system.cpu.state + type: + allow_custom_values: true + members: + - id: user + value: 'user' + stability: experimental + - id: system + value: 'system' + stability: experimental + - id: nice + value: 'nice' + stability: experimental + - id: idle + value: 'idle' + stability: experimental + - id: iowait + value: 'iowait' + stability: experimental + - id: interrupt + value: 'interrupt' + stability: experimental + - id: steal + value: 'steal' + stability: experimental + brief: "Deprecated, use `cpu.mode` instead." + stability: experimental + deprecated: 'Replaced by `cpu.mode`' + examples: [ "idle", "interrupt" ] diff --git a/model/registry/process.yaml b/model/registry/process.yaml index 54c9a6fb40..7cb7451e66 100644 --- a/model/registry/process.yaml +++ b/model/registry/process.yaml @@ -196,26 +196,3 @@ groups: value: 'minor' stability: experimental stability: experimental - - - id: registry.process.cpu - prefix: process.cpu - type: attribute_group - brief: > - Attributes for process CPU - attributes: - - id: state - brief: > - The CPU state of the process. - type: - allow_custom_values: true - members: - - id: system - value: 'system' - stability: experimental - - id: user - value: 'user' - stability: experimental - - id: wait - value: 'wait' - stability: experimental - stability: experimental diff --git a/model/registry/system.yaml b/model/registry/system.yaml index d407f96d56..790a1374af 100644 --- a/model/registry/system.yaml +++ b/model/registry/system.yaml @@ -16,34 +16,6 @@ groups: type: attribute_group brief: "Describes System CPU attributes" attributes: - - id: state - type: - allow_custom_values: true - members: - - id: user - value: 'user' - stability: experimental - - id: system - value: 'system' - stability: experimental - - id: nice - value: 'nice' - stability: experimental - - id: idle - value: 'idle' - stability: experimental - - id: iowait - value: 'iowait' - stability: experimental - - id: interrupt - value: 'interrupt' - stability: experimental - - id: steal - value: 'steal' - stability: experimental - brief: "The state of the CPU" - stability: experimental - examples: ["idle", "interrupt"] - id: logical_number type: int stability: experimental diff --git a/schema-next.yaml b/schema-next.yaml index 9469bc54eb..f87f1059d9 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -41,7 +41,18 @@ versions: # https://github.com/open-telemetry/semantic-conventions/pull/1006 - rename_metrics: messaging.publish.messages: messaging.client.published.messages - + # https://github.com/open-telemetry/semantic-conventions/pull/1026 + - rename_attributes: + attribute_map: + system.cpu.state: cpu.mode + process.cpu.state: cpu.mode + container.cpu.state: cpu.mode + apply_to_metrics: + - system.cpu.time + - system.cpu.utilization + - process.cpu.time + - process.cpu.utilization + - container.cpu.time 1.26.0: metrics: changes: diff --git a/templates/registry/markdown/weaver.yaml b/templates/registry/markdown/weaver.yaml index 19cbd089a6..64e16bead2 100644 --- a/templates/registry/markdown/weaver.yaml +++ b/templates/registry/markdown/weaver.yaml @@ -10,6 +10,7 @@ acronyms: - iOS - AWS - CloudEvents + - CPU - CosmosDB - DynamoDB - ECS From 5a2836bbea0b6e105b98370f331a7661bcf19540 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 26 Jun 2024 10:19:45 +0100 Subject: [PATCH 03/23] Update kafka spring example to align with the spec (#1155) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/1155.yaml | 4 +++ docs/messaging/kafka.md | 77 +++++++++++++++++++++++------------------ 2 files changed, 47 insertions(+), 34 deletions(-) create mode 100644 .chloggen/1155.yaml diff --git a/.chloggen/1155.yaml b/.chloggen/1155.yaml new file mode 100644 index 0000000000..4b71d69ec3 --- /dev/null +++ b/.chloggen/1155.yaml @@ -0,0 +1,4 @@ +change_type: bug_fix +component: messaging +note: Update Kafka Spring example to align with the messaging spec +issues: [ 1155 ] diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index cb477b56d2..14b01a072d 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -138,41 +138,50 @@ If an intermediary broker is present, `service.name` and `peer.service` will not ### Apache Kafka with Quarkus or Spring Boot Example -Given is a process P, that publishes a message to a topic T1 on Apache Kafka. -One process, CA, receives the message and publishes a new message to a topic T2 that is then received and processed by CB. - -Frameworks such as Quarkus and Spring Boot separate processing of a received message from producing subsequent messages out. -For this reason, receiving (Span Rcv1) is the parent of both processing (Span Proc1) and producing a new message (Span Prod2). -The span representing message receiving (Span Rcv1) should set `messaging.operation.type` to `process`, -as it does not only receive the message but also converts the input message to something suitable for the processing operation to consume and creates the output message from the result of processing. - -``` -Process P: | Span Prod1 | --- -Process CA: | Span Rcv1 | - | Span Proc1 | - | Span Prod2 | --- -Process CB: | Span Rcv2 | +In this example, the producer publishes a message to a topic T on Apache Kafka. +Consumer receives the message, processes it and commits the offset. + +Frameworks such as Quarkus and Spring Boot provide integrations with Kafka allowing to +configure and instrument processing callbacks, so corresponding instrumentations should create "Process" +spans in addition to "Receive" spans created by Kafka instrumentations for polling calls. + +```mermaid +flowchart LR; + subgraph PRODUCER + P[Span Send] + end + subgraph CONSUMER + direction TB + R1[Span Poll] + R2[Span Process] + R3[Span Commit] + end + + P-. link .-R1; + P-. link .-R2; + R2-- parent ---R3; + + classDef normal fill:green + class P,R1,R2,R3 normal + linkStyle 0 color:green,stroke:green + linkStyle 1 color:green,stroke:green ``` -| Field or Attribute | Span Prod1 | Span Rcv1 | Span Proc1 | Span Prod2 | Span Rcv2 | -|-|-|-|-|-|-| -| Span name | `"send T1"` | `"send T1"` | `"process T1"` | `"send T2"` | `"poll T2`" | -| Parent | | Span Prod1 | Span Rcv1 | Span Rcv1 | Span Prod2 | -| Links | | | | | | -| SpanKind | `PRODUCER` | `CONSUMER` | `CONSUMER` | `PRODUCER` | `CONSUMER` | -| Status | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` | -| `peer.service` | `"myKafka"` | | | `"myKafka"` | | -| `service.name` | | `"myConsumer1"` | `"myConsumer1"` | | `"myConsumer2"` | -| `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | -| `messaging.destination.name` | `"T1"` | `"T1"` | `"T1"` | `"T2"` | `"T2"` | -| `messaging.operation.name` | `send` | `send` | `"process"` | `send` | `"poll"` | -| `messaging.operation.type` | `publish` | `publish` | `"process"` | `publish` | `"receive"` | -| `messaging.client.id` | | `"5"` | `"5"` | `"5"` | `"8"` | -| `messaging.kafka.message.key` | `"myKey"` | `"myKey"` | `"myKey"` | `"anotherKey"` | `"anotherKey"` | -| `messaging.kafka.consumer.group` | | `"my-group"` | `"my-group"` | | `"another-group"` | -| `messaging.kafka.destination.partition` | `"1"` | `"1"` | `"1"` | `"3"` | `"3"` | -| `messaging.kafka.message.offset` | `"12"` | `"12"` | `"12"` | `"32"` | `"32"` | +| Field or Attribute | Span Send | Span Poll | Span Process | Span Commit T | +|-|-|-|-|-| +| Span name | `"send T"` | `"poll T"` | `"process T"` | `"commit T"` | +| Parent | | | (optional) Span Send | Span Process | +| Links | | Span Send | Span Send | | +| SpanKind | `PRODUCER` | `CONSUMER` | `SERVER` | `CLIENT` | +| Status | `UNSET` | `UNSET` | `UNSET` | `UNSET` | +| `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | +| `messaging.destination.name` | `"T"` | `"T"` | `"T"` | `"T"` | +| `messaging.destination.consumer.group` | | `"my-group"` | `"my-group"` | `"my-group"` | +| `messaging.destination.partition.id` | `"1"` | `"1"` | `"1"` | `"1"` | +| `messaging.operation.name` | `"send"` | `"poll"` | `"process"` | `"commit"` | +| `messaging.operation.type` | `"publish"` | `"receive"` | `"process"` | `"settle"` | +| `messaging.client.id` | `"5"` | `"8"` | `"8"` | `"8"` | +| `messaging.kafka.message.key` | `"myKey"` | `"myKey"` | `"myKey"` | | +| `messaging.kafka.message.offset` | | `"12"` | `"12"` | `"12"` | [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status From a328d73b5b2bd8e22735dd2f0222a14daf9a8902 Mon Sep 17 00:00:00 2001 From: Ashok Chandrasekar Date: Thu, 27 Jun 2024 11:05:12 +0000 Subject: [PATCH 04/23] Add LLM model server metrics (#1103) Co-authored-by: Liudmila Molkova Co-authored-by: Drew Robbins Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/1102.yaml | 22 +++ docs/attributes-registry/gen-ai.md | 2 +- docs/gen-ai/gen-ai-metrics.md | 246 +++++++++++++++++++++++++++-- docs/gen-ai/gen-ai-spans.md | 2 +- model/metrics/gen-ai.yaml | 36 +++++ model/registry/gen-ai.yaml | 2 +- 6 files changed, 298 insertions(+), 12 deletions(-) create mode 100755 .chloggen/1102.yaml diff --git a/.chloggen/1102.yaml b/.chloggen/1102.yaml new file mode 100755 index 0000000000..b80789491d --- /dev/null +++ b/.chloggen/1102.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: gen-ai + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add GenAI model server metrics for measuring LLM serving latency + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1102] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/attributes-registry/gen-ai.md b/docs/attributes-registry/gen-ai.md index 36a69ad7dc..7030cb3bd3 100644 --- a/docs/attributes-registry/gen-ai.md +++ b/docs/attributes-registry/gen-ai.md @@ -26,7 +26,7 @@ This document defines the attributes used to describe telemetry in the context o | `gen_ai.response.finish_reasons` | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.response.id` | string | The unique identifier for the completion. | `chatcmpl-123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.response.model` | string | The name of the model that generated the response. | `gpt-4-0613` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.system` | string | The Generative AI product as identified by the client instrumentation. [3] | `openai` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.system` | string | The Generative AI product as identified by the client or server instrumentation. [3] | `openai` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.token.type` | string | The type of token being counted. | `input`; `output` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.usage.completion_tokens` | int | The number of tokens used in the GenAI response (completion). | `180` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.usage.prompt_tokens` | int | The number of tokens used in the GenAI input or prompt. | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/gen-ai/gen-ai-metrics.md b/docs/gen-ai/gen-ai-metrics.md index 8e381c00db..9f8e165cff 100644 --- a/docs/gen-ai/gen-ai-metrics.md +++ b/docs/gen-ai/gen-ai-metrics.md @@ -2,16 +2,10 @@ linkTitle: Generative AI metrics ---> -# Semantic Conventions for Generative AI Client Metrics +# Semantic Conventions for Generative AI Metrics **Status**: [Experimental][DocumentStatus] -The conventions described in this section are specific to Generative AI client -applications. - -**Disclaimer:** These are initial Generative AI client metric instruments -and attributes but more may be added in the future. - @@ -19,11 +13,21 @@ and attributes but more may be added in the future. - [Generative AI Client Metrics](#generative-ai-client-metrics) - [Metric: `gen_ai.client.token.usage`](#metric-gen_aiclienttokenusage) - [Metric: `gen_ai.client.operation.duration`](#metric-gen_aiclientoperationduration) +- [Generative AI Model Server Metrics](#generative-ai-model-server-metrics) + - [Metric: `gen_ai.server.request.duration`](#metric-gen_aiserverrequestduration) + - [Metric: `gen_ai.server.time_per_output_token`](#metric-gen_aiservertime_per_output_token) + - [Metric: `gen_ai.server.time_to_first_token`](#metric-gen_aiservertime_to_first_token) ## Generative AI Client Metrics +The conventions described in this section are specific to Generative AI client +applications. + +**Disclaimer:** These are initial Generative AI client metric instruments +and attributes but more may be added in the future. + The following metric instruments describe Generative AI operations. An operation may be a request to an LLM, a function call, or some other distinct action within a larger Generative AI workflow. @@ -69,7 +73,7 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of [1, 4, 16, 64 |---|---|---|---|---|---| | [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. | `chat`; `completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.token.type`](/docs/attributes-registry/gen-ai.md) | string | The type of token being counted. | `input`; `output` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -142,7 +146,7 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of [ 0.01, 0.02, |---|---|---|---|---|---| | [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. | `chat`; `completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -179,6 +183,230 @@ Instrumentations SHOULD document the list of errors they report. + + + + + +## Generative AI Model Server Metrics + +The following metric instruments describe Generative AI model servers' +operational metrics. It includes both functional and performance metrics. + +### Metric: `gen_ai.server.request.duration` + +This metric is [recommended][MetricRecommended] to report the model server +latency in terms of time spent per request. + +This metric SHOULD be specified with [ExplicitBucketBoundaries] of +[0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12,10.24, 20.48, 40.96, 81.92]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `gen_ai.server.request.duration` | Histogram | `s` | Generative AI server request duration such as time-to-last byte or last output token | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. | `chat`; `completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. +For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +**[2]:** The `error.type` SHOULD match the error code returned by the Generative AI service, +the canonical name of exception that occurred, or another low-cardinality error identifier. +Instrumentations SHOULD document the list of errors they report. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + + + +`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +`gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `gen_ai.server.time_per_output_token` + +This metric is [recommended][MetricRecommended] to report the model server +latency in terms of time per token generated after the first token for any model +servers which support serving LLMs. It is measured by subtracting the time taken +to generate the first output token from the request duration and dividing the +rest of the duration by the number of output tokens generated after the first +token. This is important in measuring the performance of the decode phase of LLM +inference. + +This metric SHOULD be specified with [ExplicitBucketBoundaries] of +[0.01, 0.025, 0.05, 0.075, 0.1, 0.15, 0.2, 0.3, 0.4, 0.5, 0.75, 1.0, 2.5]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `gen_ai.server.time_per_output_token` | Histogram | `s` | Time per output token generated after the first token for successful responses | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. | `chat`; `completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. +For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + + + +`gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `gen_ai.server.time_to_first_token` + +This metric is [recommended][MetricRecommended] to report the model server +latency in terms of time spent to generate the first token of the response for +any model servers which support serving LLMs. It helps measure the time spent in +the queue and the prefill phase. It is important especially for streaming +requests. It is calculated at a request level and is reported as a histogram +using the buckets mentioned below. + +This metric SHOULD be specified with [ExplicitBucketBoundaries] of +[0.001, 0.005, 0.01, 0.02, 0.04, 0.06, 0.08, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `gen_ai.server.time_to_first_token` | Histogram | `s` | Time to generate first token for successful responses | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. | `chat`; `completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. +For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + + + +`gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md index d6837106df..d2fb54b987 100644 --- a/docs/gen-ai/gen-ai-spans.md +++ b/docs/gen-ai/gen-ai-spans.md @@ -46,7 +46,7 @@ These attributes track input data and metadata for a request to an GenAI model. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [1] | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.presence_penalty`](/docs/attributes-registry/gen-ai.md) | double | The presence penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/metrics/gen-ai.yaml b/model/metrics/gen-ai.yaml index 8398e8f0c6..7c9979cf21 100644 --- a/model/metrics/gen-ai.yaml +++ b/model/metrics/gen-ai.yaml @@ -16,6 +16,18 @@ groups: requirement_level: required - ref: gen_ai.operation.name requirement_level: required + - id: metric_attributes.gen_ai.server + type: attribute_group + brief: 'This group describes GenAI server metrics attributes' + extends: metric_attributes.gen_ai + attributes: + - ref: error.type + requirement_level: + conditionally_required: "if the operation ended in an error" + note: | + The `error.type` SHOULD match the error code returned by the Generative AI service, + the canonical name of exception that occurred, or another low-cardinality error identifier. + Instrumentations SHOULD document the list of errors they report. - id: metric.gen_ai.client.token.usage type: metric metric_name: gen_ai.client.token.usage @@ -43,3 +55,27 @@ groups: The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. + - id: metric.gen_ai.server.request.duration + type: metric + metric_name: gen_ai.server.request.duration + brief: 'Generative AI server request duration such as time-to-last byte or last output token' + instrument: histogram + unit: "s" + stability: experimental + extends: metric_attributes.gen_ai.server + - id: metric.gen_ai.server.time_per_output_token + type: metric + metric_name: gen_ai.server.time_per_output_token + brief: 'Time per output token generated after the first token for successful responses' + instrument: histogram + unit: "s" + stability: experimental + extends: metric_attributes.gen_ai + - id: metric.gen_ai.server.time_to_first_token + type: metric + metric_name: gen_ai.server.time_to_first_token + brief: 'Time to generate first token for successful responses' + instrument: histogram + unit: "s" + stability: experimental + extends: metric_attributes.gen_ai diff --git a/model/registry/gen-ai.yaml b/model/registry/gen-ai.yaml index 394f053a21..2bbf16e7c4 100644 --- a/model/registry/gen-ai.yaml +++ b/model/registry/gen-ai.yaml @@ -25,7 +25,7 @@ groups: stability: experimental value: "cohere" brief: 'Cohere' - brief: The Generative AI product as identified by the client instrumentation. + brief: The Generative AI product as identified by the client or server instrumentation. note: > The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` From ba4c418ff7736a5878f9782211a02f207aadbfe3 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 27 Jun 2024 09:48:09 -0700 Subject: [PATCH 05/23] Remove unreleased section from the middle of the changelog (#1189) --- CHANGELOG.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a4f606d30..dd3b88f886 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,7 +26,7 @@ - `device.app.lifecycle`: Reformat and update the `device.app.lifecycle` event description adds constraints for the possible values of the `android.state` and `ios.state`. (#794) Removes the `ios.lifecycle.events` and `android.lifecycle.events` attributes from the global registry and adds constraints for the possible values of the `android.state` and `ios.state` attributes. - + - `messaging`: Rename `messaging.client_id` to `messaging.client.id` (#935) - `rpc`: Rename`message.*` attributes under `rpc` to `rpc.message.*`. Deprecate old `message.*` attributes. (#854) @@ -51,7 +51,7 @@ The entirety of the registry now is generated using weaver with templates under the `templates/` directory. Snippets still require a hardcoded command. - + - `http`: List all HTTP client and server attributes in the corresponding table, remove common attributes from yaml and markdown. (#928) - `other`: Document patterns and suggestions for semconv code generation. (#551, #953) - `db`: Show applicable common attributes in individual database semantic conventions. (#973) @@ -72,14 +72,6 @@ - `net`: Add previously deprecated net attributes to registry (#1029) These attributes were deprecated in 1.13 -## Unreleased - -### Breaking - -### Features - -### Fixes - ## v1.25.0 ### 🛑 Breaking changes 🛑 From 5077fd5ccf64e3ad0821866cc80d77bb24098ba2 Mon Sep 17 00:00:00 2001 From: Marylia Gutierrez Date: Fri, 28 Jun 2024 15:10:11 -0400 Subject: [PATCH 06/23] Add node.js runtime metrics semantic conventions (#991) Signed-off-by: maryliag Co-authored-by: Liudmila Molkova --- .chloggen/nodejs-metrics.yaml | 17 ++ docs/runtime/README.md | 3 +- docs/runtime/nodejs-metrics.md | 343 ++++++++++++++++++++++++ model/metrics/nodejs-metrics.yaml | 81 ++++++ templates/registry/markdown/weaver.yaml | 1 + 5 files changed, 444 insertions(+), 1 deletion(-) create mode 100755 .chloggen/nodejs-metrics.yaml create mode 100644 docs/runtime/nodejs-metrics.md create mode 100644 model/metrics/nodejs-metrics.yaml diff --git a/.chloggen/nodejs-metrics.yaml b/.chloggen/nodejs-metrics.yaml new file mode 100755 index 0000000000..51b11a961e --- /dev/null +++ b/.chloggen/nodejs-metrics.yaml @@ -0,0 +1,17 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: new_component + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: nodejs + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Introducing semantic conventions for Node.js runtime metrics. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [990] diff --git a/docs/runtime/README.md b/docs/runtime/README.md index bcabd1d7b6..0d0dd6033f 100644 --- a/docs/runtime/README.md +++ b/docs/runtime/README.md @@ -47,8 +47,9 @@ Also consider the [OS process metrics](/docs/system/process-metrics.md) semantic conventions when instrumenting runtime environments. -- [JVM](jvm-metrics.md) - [Go](go-metrics.md) +- [JVM](jvm-metrics.md) +- [Node.js](nodejs-metrics.md) ### Attributes diff --git a/docs/runtime/nodejs-metrics.md b/docs/runtime/nodejs-metrics.md new file mode 100644 index 0000000000..60fcd283af --- /dev/null +++ b/docs/runtime/nodejs-metrics.md @@ -0,0 +1,343 @@ + + +# Semantic Conventions for Node.js Runtime Metrics + +**Status**: [Experimental][DocumentStatus] + +This document describes semantic conventions for Node.js Runtime metrics in OpenTelemetry. + + + + + +- [Experimental](#experimental) + - [Metric: `nodejs.eventloop.delay.min`](#metric-nodejseventloopdelaymin) + - [Metric: `nodejs.eventloop.delay.max`](#metric-nodejseventloopdelaymax) + - [Metric: `nodejs.eventloop.delay.mean`](#metric-nodejseventloopdelaymean) + - [Metric: `nodejs.eventloop.delay.stddev`](#metric-nodejseventloopdelaystddev) + - [Metric: `nodejs.eventloop.delay.p50`](#metric-nodejseventloopdelayp50) + - [Metric: `nodejs.eventloop.delay.p90`](#metric-nodejseventloopdelayp90) + - [Metric: `nodejs.eventloop.delay.p99`](#metric-nodejseventloopdelayp99) + - [Metric: `nodejs.eventloop.utilization`](#metric-nodejseventlooputilization) + + + +## Experimental + +**Status**: [Experimental][DocumentStatus] + +**Description:** Experimental Node.js Runtime metrics captured under `nodejs`. + +Note: The metrics for eventloop delay are split into separated values instead of a single histogram, because node runtime +only returns single values through [`perf_hooks.monitorEventLoopDelay([options])`][Eventloop] and not the entire +histogram, so it's not possible to convert it to an OpenTelemetry histogram. + +### Metric: `nodejs.eventloop.delay.min` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.min` | Gauge | `s` | Event loop minimum delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.min` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.max` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.max` | Gauge | `s` | Event loop maximum delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.max` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.mean` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.mean` | Gauge | `s` | Event loop mean delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.mean` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.stddev` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.stddev` | Gauge | `s` | Event loop standard deviation delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.stddev` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.p50` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.p50` | Gauge | `s` | Event loop 50 percentile delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.percentile(50)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.p90` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.p90` | Gauge | `s` | Event loop 90 percentile delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.percentile(90)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.delay.p99` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.delay.p99` | Gauge | `s` | Event loop 99 percentile delay. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `histogram.percentile(99)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + + + + + + + + + + + + + + + + + + + + +### Metric: `nodejs.eventloop.utilization` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `nodejs.eventloop.utilization` | Gauge | `1` | Event loop utilization. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** The value range is [0.0,1.0] and can be retrieved from value [`performance.eventLoopUtilization([utilization1[, utilization2]])`](https://nodejs.org/api/perf_hooks.html#performanceeventlooputilizationutilization1-utilization2) + + + + + + + + + + + + + + + + + + + + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended +[Eventloop]: https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions diff --git a/model/metrics/nodejs-metrics.yaml b/model/metrics/nodejs-metrics.yaml new file mode 100644 index 0000000000..9def4fa143 --- /dev/null +++ b/model/metrics/nodejs-metrics.yaml @@ -0,0 +1,81 @@ +groups: + - id: metric.nodejs.eventloop.delay.min + type: metric + metric_name: nodejs.eventloop.delay.min + brief: "Event loop minimum delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.min` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.max + type: metric + metric_name: nodejs.eventloop.delay.max + brief: "Event loop maximum delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.max` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.mean + type: metric + metric_name: nodejs.eventloop.delay.mean + brief: "Event loop mean delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.mean` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.stddev + type: metric + metric_name: nodejs.eventloop.delay.stddev + brief: "Event loop standard deviation delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.stddev` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.pfifty + type: metric + metric_name: nodejs.eventloop.delay.p50 + brief: "Event loop 50 percentile delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.percentile(50)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.pninety + type: metric + metric_name: nodejs.eventloop.delay.p90 + brief: "Event loop 90 percentile delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.percentile(90)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.delay.pninety_nine + type: metric + metric_name: nodejs.eventloop.delay.p99 + brief: "Event loop 99 percentile delay." + instrument: gauge + unit: "s" + stability: experimental + note: > + Value can be retrieved from value `histogram.percentile(99)` of [`perf_hooks.monitorEventLoopDelay([options])`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions) + + - id: metric.nodejs.eventloop.utilization + type: metric + metric_name: nodejs.eventloop.utilization + brief: "Event loop utilization." + instrument: gauge + unit: "1" + stability: experimental + note: > + The value range is [0.0,1.0] and can be retrieved from value + [`performance.eventLoopUtilization([utilization1[, utilization2]])`](https://nodejs.org/api/perf_hooks.html#performanceeventlooputilizationutilization1-utilization2) diff --git a/templates/registry/markdown/weaver.yaml b/templates/registry/markdown/weaver.yaml index 64e16bead2..f698ae6754 100644 --- a/templates/registry/markdown/weaver.yaml +++ b/templates/registry/markdown/weaver.yaml @@ -20,6 +20,7 @@ acronyms: - GCE - HTTP - JVM + - NodeJS - OCI - OTel - OpenTracing From 0f067bb98f9e5a008f837a02edc43a1fdc4339ed Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Wed, 3 Jul 2024 12:25:43 -0400 Subject: [PATCH 07/23] Bump weaver to latest version. (#1207) --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 1b6b4f499d..b2af508988 100644 --- a/Makefile +++ b/Makefile @@ -14,7 +14,7 @@ CHLOGGEN_CONFIG := .chloggen/config.yaml # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates # Keep links in model/README.md and .vscode/settings.json in sync! SEMCONVGEN_VERSION=0.24.0 -WEAVER_VERSION=0.2.0 +WEAVER_VERSION=0.5.0 # From where to resolve the containers (e.g. "otel/weaver"). CONTAINER_REPOSITORY=docker.io From 5971366ae2fcaf2d01b1a52da92e872b7df5491d Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 4 Jul 2024 08:41:54 -0700 Subject: [PATCH 08/23] GenAI: Rename prompt and completion tokens attributes to input and output (#1200) --- .chloggen/1200.yaml | 6 ++++++ docs/attributes-registry/gen-ai.md | 16 ++++++++++++++-- docs/gen-ai/gen-ai-spans.md | 4 ++-- model/registry/deprecated/gen-ai.yaml | 17 +++++++++++++++++ model/registry/gen-ai.yaml | 6 +++--- model/trace/gen-ai.yaml | 4 ++-- schema-next.yaml | 5 +++++ 7 files changed, 49 insertions(+), 9 deletions(-) create mode 100644 .chloggen/1200.yaml create mode 100644 model/registry/deprecated/gen-ai.yaml diff --git a/.chloggen/1200.yaml b/.chloggen/1200.yaml new file mode 100644 index 0000000000..9d40d16961 --- /dev/null +++ b/.chloggen/1200.yaml @@ -0,0 +1,6 @@ +change_type: enhancement +component: gen_ai +note: > + Rename `gen_ai.usage.prompt_tokens` to `gen_ai.usage.input_tokens` and `gen_ai.usage.completion_tokens` to `gen_ai.usage.output_tokens` + to align terminology between spans and metrics. +issues: [ 1200 ] diff --git a/docs/attributes-registry/gen-ai.md b/docs/attributes-registry/gen-ai.md index 7030cb3bd3..753b0c35e1 100644 --- a/docs/attributes-registry/gen-ai.md +++ b/docs/attributes-registry/gen-ai.md @@ -6,6 +6,9 @@ # Gen AI +- [Gen Ai](#gen-ai-attributes) +- [Gen Ai Deprecated](#gen-ai-deprecated-attributes) + ## Gen AI Attributes This document defines the attributes used to describe telemetry in the context of Generative Artificial Intelligence (GenAI) Models requests and responses. @@ -28,8 +31,8 @@ This document defines the attributes used to describe telemetry in the context o | `gen_ai.response.model` | string | The name of the model that generated the response. | `gpt-4-0613` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.system` | string | The Generative AI product as identified by the client or server instrumentation. [3] | `openai` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.token.type` | string | The type of token being counted. | `input`; `output` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.usage.completion_tokens` | int | The number of tokens used in the GenAI response (completion). | `180` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.usage.prompt_tokens` | int | The number of tokens used in the GenAI input or prompt. | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.usage.input_tokens` | int | The number of tokens used in the GenAI input (prompt). | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.usage.output_tokens` | int | The number of tokens used in the GenAI response (completion). | `180` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) @@ -53,3 +56,12 @@ For custom model, a custom friendly name SHOULD be used. If none of these option | -------- | ------------------------------------------ | ---------------------------------------------------------------- | | `input` | Input tokens (prompt, input, etc.) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `output` | Output tokens (completion, response, etc.) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Gen AI Deprecated Attributes + +Describes deprecated `gen_ai` attributes. + +| Attribute | Type | Description | Examples | Stability | +| -------------------------------- | ---- | ----------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | +| `gen_ai.usage.completion_tokens` | int | Deprecated, use `gen_ai.usage.output_tokens` instead. | `42` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `gen_ai.usage.output_tokens` attribute. | +| `gen_ai.usage.prompt_tokens` | int | Deprecated, use `gen_ai.usage.input_tokens` instead. | `42` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `gen_ai.usage.input_tokens` attribute. | diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md index d2fb54b987..1615d18c48 100644 --- a/docs/gen-ai/gen-ai-spans.md +++ b/docs/gen-ai/gen-ai-spans.md @@ -57,8 +57,8 @@ These attributes track input data and metadata for a request to an GenAI model. | [`gen_ai.response.finish_reasons`](/docs/attributes-registry/gen-ai.md) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [3] | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.usage.completion_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI response (completion). | `180` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.usage.prompt_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI input or prompt. | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI input (prompt). | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI response (completion). | `180` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. diff --git a/model/registry/deprecated/gen-ai.yaml b/model/registry/deprecated/gen-ai.yaml new file mode 100644 index 0000000000..ca6abd6732 --- /dev/null +++ b/model/registry/deprecated/gen-ai.yaml @@ -0,0 +1,17 @@ +groups: + - id: registry.gen_ai.deprecated + type: attribute_group + brief: Describes deprecated `gen_ai` attributes. + attributes: + - id: gen_ai.usage.prompt_tokens + type: int + stability: experimental + deprecated: Replaced by `gen_ai.usage.input_tokens` attribute. + brief: "Deprecated, use `gen_ai.usage.input_tokens` instead." + examples: [42] + - id: gen_ai.usage.completion_tokens + type: int + stability: experimental + deprecated: Replaced by `gen_ai.usage.output_tokens` attribute. + brief: "Deprecated, use `gen_ai.usage.output_tokens` instead." + examples: [42] diff --git a/model/registry/gen-ai.yaml b/model/registry/gen-ai.yaml index 2bbf16e7c4..06b994bfc0 100644 --- a/model/registry/gen-ai.yaml +++ b/model/registry/gen-ai.yaml @@ -90,12 +90,12 @@ groups: type: string[] brief: Array of reasons the model stopped generating tokens, corresponding to each generation received. examples: ['stop'] - - id: usage.prompt_tokens + - id: usage.input_tokens stability: experimental type: int - brief: The number of tokens used in the GenAI input or prompt. + brief: The number of tokens used in the GenAI input (prompt). examples: [100] - - id: usage.completion_tokens + - id: usage.output_tokens stability: experimental type: int brief: The number of tokens used in the GenAI response (completion). diff --git a/model/trace/gen-ai.yaml b/model/trace/gen-ai.yaml index ef77733e83..1c2418efab 100644 --- a/model/trace/gen-ai.yaml +++ b/model/trace/gen-ai.yaml @@ -36,9 +36,9 @@ groups: fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. - ref: gen_ai.response.finish_reasons requirement_level: recommended - - ref: gen_ai.usage.prompt_tokens + - ref: gen_ai.usage.input_tokens requirement_level: recommended - - ref: gen_ai.usage.completion_tokens + - ref: gen_ai.usage.output_tokens requirement_level: recommended events: - gen_ai.content.prompt diff --git a/schema-next.yaml b/schema-next.yaml index f87f1059d9..b2d310bd77 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -11,6 +11,11 @@ versions: messaging.rocketmq.client_group: messaging.consumer.group.name messaging.evenhubs.consumer.group: messaging.consumer.group.name message.servicebus.destination.subscription_name: messaging.destination.subscription.name + # https://github.com/open-telemetry/semantic-conventions/pull/1200 + - rename_attributes: + attribute_map: + gen_ai.usage.completion_tokens: gen_ai.usage.output_tokens + gen_ai.usage.prompt_tokens: gen_ai.usage.input_tokens spans: changes: # https://github.com/open-telemetry/semantic-conventions/pull/1002 From b1ad9ae785c3d97cf0c80fe320d9b9156f37e927 Mon Sep 17 00:00:00 2001 From: Marylia Gutierrez Date: Mon, 8 Jul 2024 10:25:55 -0400 Subject: [PATCH 09/23] Add v8 js engine runtime metrics semantic conventions (#1066) Signed-off-by: maryliag Co-authored-by: Liudmila Molkova Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/v8js-metrics.yaml | 17 ++ .github/ISSUE_TEMPLATE/bug_report.yaml | 1 + .github/ISSUE_TEMPLATE/change_proposal.yaml | 1 + .github/ISSUE_TEMPLATE/new-conventions.yaml | 1 + docs/attributes-registry/README.md | 1 + docs/attributes-registry/v8js.md | 37 +++ docs/runtime/README.md | 1 + docs/runtime/v8js-metrics.md | 315 ++++++++++++++++++++ model/metrics/v8js-metrics.yaml | 69 +++++ model/registry/v8js.yaml | 54 ++++ 10 files changed, 497 insertions(+) create mode 100644 .chloggen/v8js-metrics.yaml create mode 100644 docs/attributes-registry/v8js.md create mode 100644 docs/runtime/v8js-metrics.md create mode 100644 model/metrics/v8js-metrics.yaml create mode 100644 model/registry/v8js.yaml diff --git a/.chloggen/v8js-metrics.yaml b/.chloggen/v8js-metrics.yaml new file mode 100644 index 0000000000..276a49d500 --- /dev/null +++ b/.chloggen/v8js-metrics.yaml @@ -0,0 +1,17 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: new_component + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: v8js + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Introducing semantic conventions for V8 JS Engine runtime metrics. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [990] diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index f4add087f9..92d1f8f1e3 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -72,6 +72,7 @@ body: - area:url - area:user-agent - area:user + - area:v8js - area:webengine # End semconv area list - type: textarea diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index e5c7532f76..bb06caa150 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -65,6 +65,7 @@ body: - area:url - area:user-agent - area:user + - area:v8js - area:webengine # End semconv area list - type: textarea diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index b4099a42cb..01b2c53764 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -74,6 +74,7 @@ body: - area:url - area:user-agent - area:user + - area:v8js - area:webengine # End semconv area list - type: textarea diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 97eab1087b..fe0413bb19 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -86,6 +86,7 @@ Currently, the following namespaces exist: - [URL](url.md) - [User](user.md) - [User Agent](user-agent.md) +- [V8js](v8js.md) - [Webengine](webengine.md) [developers recommendations]: ../general/attribute-naming.md#recommendations-for-application-developers diff --git a/docs/attributes-registry/v8js.md b/docs/attributes-registry/v8js.md new file mode 100644 index 0000000000..2e2bf3fec3 --- /dev/null +++ b/docs/attributes-registry/v8js.md @@ -0,0 +1,37 @@ + + + + + +# V8js + +## V8js Attributes + +Describes V8 JS Engine Runtime related attributes. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------- | ------ | ---------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------- | +| `v8js.gc.type` | string | The type of garbage collection. | `major`; `minor`; `incremental` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `v8js.heap.space.name` | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + +`v8js.gc.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------------- | ---------------------------------------- | ---------------------------------------------------------------- | +| `incremental` | Incremental (Incremental Marking). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `major` | Major (Mark Sweep Compact). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `minor` | Minor (Scavenge). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `weakcb` | Weak Callbacks (Process Weak Callbacks). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`v8js.heap.space.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| -------------------- | -------------------------- | ---------------------------------------------------------------- | +| `code_space` | Code memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/runtime/README.md b/docs/runtime/README.md index 0d0dd6033f..7f17940f36 100644 --- a/docs/runtime/README.md +++ b/docs/runtime/README.md @@ -50,6 +50,7 @@ semantic conventions when instrumenting runtime environments. - [Go](go-metrics.md) - [JVM](jvm-metrics.md) - [Node.js](nodejs-metrics.md) +- [V8 JS Engine](v8js-metrics.md) ### Attributes diff --git a/docs/runtime/v8js-metrics.md b/docs/runtime/v8js-metrics.md new file mode 100644 index 0000000000..d8b4e07a65 --- /dev/null +++ b/docs/runtime/v8js-metrics.md @@ -0,0 +1,315 @@ + + +# Semantic Conventions for V8 JS Engine Runtime Metrics + +**Status**: [Experimental][DocumentStatus] + +This document describes semantic conventions for V8 JS Engine Runtime metrics in OpenTelemetry. This engine is used in some javascript runtime such as Node.js and Deno. + + + + + +- [Experimental](#experimental) + - [Metric: `v8js.gc.duration`](#metric-v8jsgcduration) + - [Metric: `v8js.memory.heap.limit`](#metric-v8jsmemoryheaplimit) + - [Metric: `v8js.memory.heap.used`](#metric-v8jsmemoryheapused) + - [Metric: `v8js.heap.space.available_size`](#metric-v8jsheapspaceavailable_size) + - [Metric: `v8js.heap.space.physical_size`](#metric-v8jsheapspacephysical_size) + + + +## Experimental + +**Status**: [Experimental][DocumentStatus] + +**Description:** Experimental V8 JS Engine Runtime metrics captured under `v8js`. + +### Metric: `v8js.gc.duration` + +This metric is [recommended][MetricRecommended]. + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/metrics/api.md#instrument-advisory-parameters) +of `[ 0.01, 0.1, 1, 10 ]`. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `v8js.gc.duration` | Histogram | `s` | Garbage collection duration. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** The values can be retrieve from [`perf_hooks.PerformanceObserver(...).observe({ entryTypes: ['gc'] })`](https://nodejs.org/api/perf_hooks.html#performanceobserverobserveoptions) + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`v8js.gc.type`](/docs/attributes-registry/v8js.md) | string | The type of garbage collection. | `major`; `minor`; `incremental` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`v8js.gc.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `incremental` | Incremental (Incremental Marking). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `major` | Major (Mark Sweep Compact). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `minor` | Minor (Scavenge). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `weakcb` | Weak Callbacks (Process Weak Callbacks). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `v8js.memory.heap.limit` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `v8js.memory.heap.limit` | UpDownCounter | `By` | Total heap memory size pre-allocated. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** The value can be retrieved from value `space_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`v8js.heap.space.name`](/docs/attributes-registry/v8js.md) | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + +`v8js.heap.space.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `code_space` | Code memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `v8js.memory.heap.used` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `v8js.memory.heap.used` | UpDownCounter | `By` | Heap Memory size allocated. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** The value can be retrieved from value `space_used_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`v8js.heap.space.name`](/docs/attributes-registry/v8js.md) | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + +`v8js.heap.space.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `code_space` | Code memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `v8js.heap.space.available_size` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `v8js.heap.space.available_size` | UpDownCounter | `By` | Heap space available size. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `space_available_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`v8js.heap.space.name`](/docs/attributes-registry/v8js.md) | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + +`v8js.heap.space.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `code_space` | Code memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +### Metric: `v8js.heap.space.physical_size` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `v8js.heap.space.physical_size` | UpDownCounter | `By` | Committed size of a heap space. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Value can be retrieved from value `physical_space_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`v8js.heap.space.name`](/docs/attributes-registry/v8js.md) | string | The name of the space type of heap memory. [1] | `new_space`; `old_space`; `code_space` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + + +`v8js.heap.space.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `code_space` | Code memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `large_object_space` | Large object memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `map_space` | Map memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `new_space` | New memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `old_space` | Old memory space. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/model/metrics/v8js-metrics.yaml b/model/metrics/v8js-metrics.yaml new file mode 100644 index 0000000000..be0a43b09a --- /dev/null +++ b/model/metrics/v8js-metrics.yaml @@ -0,0 +1,69 @@ +groups: + - id: metric.veightjs.gc.duration + type: metric + metric_name: v8js.gc.duration + brief: "Garbage collection duration." + instrument: histogram + unit: "s" + stability: experimental + prefix: v8js.gc + attributes: + - ref: v8js.gc.type + requirement_level: required + note: > + The values can be retrieve from [`perf_hooks.PerformanceObserver(...).observe({ entryTypes: ['gc'] })`](https://nodejs.org/api/perf_hooks.html#performanceobserverobserveoptions) + + - id: metric.veightjs.memory.heap.limit + type: metric + metric_name: v8js.memory.heap.limit + brief: "Total heap memory size pre-allocated." + instrument: updowncounter + unit: "By" + stability: experimental + attributes: + - ref: v8js.heap.space.name + requirement_level: required + note: > + The value can be retrieved from value `space_size` of + [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + - id: metric.veightjs.memory.heap.used + type: metric + metric_name: v8js.memory.heap.used + brief: "Heap Memory size allocated." + instrument: updowncounter + unit: "By" + stability: experimental + attributes: + - ref: v8js.heap.space.name + requirement_level: required + note: > + The value can be retrieved from value `space_used_size` of + [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + - id: metric.veightjs.heap.space.available_size + type: metric + metric_name: v8js.heap.space.available_size + brief: "Heap space available size." + instrument: updowncounter + unit: "By" + stability: experimental + attributes: + - ref: v8js.heap.space.name + requirement_level: required + note: > + Value can be retrieved from value `space_available_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + + - id: metric.veightjs.heap.space.physical_size + type: metric + metric_name: v8js.heap.space.physical_size + brief: "Committed size of a heap space." + instrument: updowncounter + unit: "By" + stability: experimental + prefix: v8js.heap.space.physical_size + attributes: + - ref: v8js.heap.space.name + requirement_level: required + note: > + Value can be retrieved from value `physical_space_size` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) diff --git a/model/registry/v8js.yaml b/model/registry/v8js.yaml new file mode 100644 index 0000000000..a03cbe7143 --- /dev/null +++ b/model/registry/v8js.yaml @@ -0,0 +1,54 @@ +groups: + - id: registry.v8js + type: attribute_group + brief: Describes V8 JS Engine Runtime related attributes. + prefix: v8js + attributes: + - id: gc.type + stability: experimental + brief: The type of garbage collection. + type: + members: + - id: major + value: 'major' + brief: 'Major (Mark Sweep Compact).' + stability: experimental + - id: minor + value: 'minor' + brief: 'Minor (Scavenge).' + stability: experimental + - id: incremental + value: 'incremental' + brief: 'Incremental (Incremental Marking).' + stability: experimental + - id: weakcb + value: 'weakcb' + brief: 'Weak Callbacks (Process Weak Callbacks).' + stability: experimental + - id: heap.space.name + stability: experimental + brief: The name of the space type of heap memory. + note: > + Value can be retrieved from value `space_name` of [`v8.getHeapSpaceStatistics()`](https://nodejs.org/api/v8.html#v8getheapspacestatistics) + type: + members: + - id: new_space + value: 'new_space' + brief: 'New memory space.' + stability: experimental + - id: old_space + value: 'old_space' + brief: 'Old memory space.' + stability: experimental + - id: code_space + value: 'code_space' + brief: 'Code memory space.' + stability: experimental + - id: map_space + value: 'map_space' + brief: 'Map memory space.' + stability: experimental + - id: large_object_space + value: 'large_object_space' + brief: 'Large object memory space.' + stability: experimental From 8646521e49165d6f4509b65457d0be855655ad80 Mon Sep 17 00:00:00 2001 From: Armin Ruech <7052238+arminru@users.noreply.github.com> Date: Mon, 8 Jul 2024 18:48:54 +0200 Subject: [PATCH 10/23] [chore] Remove leftover TODO from CODEOWNERS (#1214) --- .github/CODEOWNERS | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index bce9f70428..f7360531b8 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -87,5 +87,3 @@ /model/metrics/process-metrics.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers /model/resource/process.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers /model/network.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers - -# TODO - Add semconv area experts From 268beb4ca3605e7f74dce655f1666dde724b72d1 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 9 Jul 2024 13:36:02 -0700 Subject: [PATCH 11/23] HTTP span status: use SHOULD instead of MUST for errors (#1167) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/1167.yaml | 4 ++++ docs/http/http-spans.md | 20 ++++++++++++++++---- 2 files changed, 20 insertions(+), 4 deletions(-) create mode 100644 .chloggen/1167.yaml diff --git a/.chloggen/1167.yaml b/.chloggen/1167.yaml new file mode 100644 index 0000000000..cc9655329e --- /dev/null +++ b/.chloggen/1167.yaml @@ -0,0 +1,4 @@ +change_type: bug_fix +component: http +note: "Relax requirement on when to set HTTP span status to Error from `MUST` to `SHOULD`." +issues: [1167, 1003] diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 180d595d41..a22e33506b 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -93,19 +93,31 @@ Instrumentation MUST NOT default to using URI path as a `{target}`. the response body; or 3xx codes with max redirects exceeded), in which case status MUST be set to `Error`. +> **Note:** +> +> The classification of an HTTP status code as an error depends on the context. +> For example, a 404 "Not Found" status code indicates an error if the application +> expected the resource to be available. However, it is not an error when the +> application is simply checking whether the resource exists. +> +> Instrumentations that have additional context about a specific request MAY use +> this context to set the span status more precisely. +> Instrumentations that don't have any additional context MUST follow the +> guidelines in this section. + For HTTP status codes in the 4xx range span status MUST be left unset in case of `SpanKind.SERVER` -and MUST be set to `Error` in case of `SpanKind.CLIENT`. +and SHOULD be set to `Error` in case of `SpanKind.CLIENT`. For HTTP status codes in the 5xx range, as well as any other code the client -failed to interpret, span status MUST be set to `Error`. +failed to interpret, span status SHOULD be set to `Error`. Don't set the span status description if the reason can be inferred from `http.response.status_code`. HTTP request may fail if it was cancelled or an error occurred preventing the client or server from sending/receiving the request/response fully. -When instrumentation detects such errors it MUST set span status to `Error` -and MUST set the `error.type` attribute. +When instrumentation detects such errors it SHOULD set span status to `Error` +and SHOULD set the `error.type` attribute. ## HTTP client From 92bd20553f969466cdc34472ce605b273dcbe017 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 9 Jul 2024 17:33:49 -0700 Subject: [PATCH 12/23] Convert `gen_ai.operation.name` to enum and use it on spans (#1202) --- .chloggen/1202.yaml | 4 + docs/attributes-registry/gen-ai.md | 28 ++++- docs/gen-ai/gen-ai-metrics.md | 173 +++++++++++++++++++++-------- docs/gen-ai/gen-ai-spans.md | 40 +++++-- model/registry/gen-ai.yaml | 21 +++- model/trace/gen-ai.yaml | 2 + 6 files changed, 206 insertions(+), 62 deletions(-) create mode 100644 .chloggen/1202.yaml diff --git a/.chloggen/1202.yaml b/.chloggen/1202.yaml new file mode 100644 index 0000000000..32e4265029 --- /dev/null +++ b/.chloggen/1202.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: gen_ai +note: Convert `gen_ai.operation.name` to enum and use it on spans +issues: [ 1202 ] diff --git a/docs/attributes-registry/gen-ai.md b/docs/attributes-registry/gen-ai.md index 753b0c35e1..a9c090a32b 100644 --- a/docs/attributes-registry/gen-ai.md +++ b/docs/attributes-registry/gen-ai.md @@ -16,8 +16,8 @@ This document defines the attributes used to describe telemetry in the context o | Attribute | Type | Description | Examples | Stability | | ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------- | | `gen_ai.completion` | string | The full response received from the GenAI model. [1] | `[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.operation.name` | string | The name of the operation being performed. | `chat`; `completion` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.prompt` | string | The full prompt sent to the GenAI model. [2] | `[{'role': 'user', 'content': 'What is the capital of France?'}]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.operation.name` | string | The name of the operation being performed. [2] | `chat`; `text_completion` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.prompt` | string | The full prompt sent to the GenAI model. [3] | `[{'role': 'user', 'content': 'What is the capital of France?'}]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.request.frequency_penalty` | double | The frequency penalty setting for the GenAI request. | `0.1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.request.max_tokens` | int | The maximum number of tokens the model generates for a request. | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.request.model` | string | The name of the GenAI model a request is being made to. | `gpt-4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -29,17 +29,33 @@ This document defines the attributes used to describe telemetry in the context o | `gen_ai.response.finish_reasons` | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.response.id` | string | The unique identifier for the completion. | `chatcmpl-123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.response.model` | string | The name of the model that generated the response. | `gpt-4-0613` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.system` | string | The Generative AI product as identified by the client or server instrumentation. [3] | `openai` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.system` | string | The Generative AI product as identified by the client or server instrumentation. [4] | `openai` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.token.type` | string | The type of token being counted. | `input`; `output` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.usage.input_tokens` | int | The number of tokens used in the GenAI input (prompt). | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.usage.output_tokens` | int | The number of tokens used in the GenAI response (completion). | `180` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) -**[2]:** It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) +**[2]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. -**[3]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. -For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. +**[3]:** It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + +**[4]:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. diff --git a/docs/gen-ai/gen-ai-metrics.md b/docs/gen-ai/gen-ai-metrics.md index 9f8e165cff..800741360b 100644 --- a/docs/gen-ai/gen-ai-metrics.md +++ b/docs/gen-ai/gen-ai-metrics.md @@ -71,22 +71,39 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of [1, 4, 16, 64 | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. | `chat`; `completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.token.type`](/docs/attributes-registry/gen-ai.md) | string | The type of token being counted. | `input`; `output` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. + +**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. -**[1]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. -For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. -**[2]:** 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. +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + `gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. @@ -144,24 +161,33 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of [ 0.01, 0.02, | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. | `chat`; `completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. -**[1]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. -For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. +**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. -**[2]:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +**[3]:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[4]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +**[5]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. @@ -172,6 +198,14 @@ Instrumentations SHOULD document the list of errors they report. | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + `gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | @@ -227,24 +261,33 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. | `chat`; `completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. -**[1]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. -For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. +**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. -**[2]:** The `error.type` SHOULD match the error code returned by the Generative AI service, +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +**[3]:** The `error.type` SHOULD match the error code returned by the Generative AI service, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[4]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +**[5]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. @@ -255,6 +298,14 @@ Instrumentations SHOULD document the list of errors they report. | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + `gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | @@ -310,20 +361,37 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. | `chat`; `completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. + +**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[1]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. -For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. -**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +| Value | Description | Stability | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. @@ -380,20 +448,37 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. | `chat`; `completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` If `sever.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. -**[1]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. -For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. +**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. -**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. -**[3]:** 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. +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + + + +`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md index 1615d18c48..e50cd6a05d 100644 --- a/docs/gen-ai/gen-ai-spans.md +++ b/docs/gen-ai/gen-ai-spans.md @@ -10,6 +10,7 @@ linkTitle: Generative AI traces +- [Name](#name) - [Configuration](#configuration) - [GenAI attributes](#genai-attributes) - [Events](#events) @@ -20,8 +21,11 @@ A request to an Generative AI is modeled as a span in a trace. **Span kind:** MUST always be `CLIENT`. -The **span name** SHOULD be set to a low cardinality value describing an operation made to an Generative AI system. -For example, the API name such as [Create chat completion](https://platform.openai.com/docs/api-reference/chat/create) could be represented as `completion gpt-4` to include the API and the model name. +## Name + +GenAI spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/trace/api.md#span). +The **span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`. +Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format. ## Configuration @@ -45,8 +49,9 @@ These attributes track input data and metadata for a request to an GenAI model. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [1] | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [2] | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [3] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.presence_penalty`](/docs/attributes-registry/gen-ai.md) | double | The presence penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -56,18 +61,35 @@ These attributes track input data and metadata for a request to an GenAI model. | [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the GenAI request. | `1.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.response.finish_reasons`](/docs/attributes-registry/gen-ai.md) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [3] | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [4] | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI input (prompt). | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI response (completion). | `180` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. +**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. + +**[2]:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + +**[3]:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. -**[2]:** The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. -For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. +**[4]:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. -**[3]:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. +`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + `gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. diff --git a/model/registry/gen-ai.yaml b/model/registry/gen-ai.yaml index 06b994bfc0..ce6755a1db 100644 --- a/model/registry/gen-ai.yaml +++ b/model/registry/gen-ai.yaml @@ -26,7 +26,10 @@ groups: value: "cohere" brief: 'Cohere' brief: The Generative AI product as identified by the client or server instrumentation. - note: > + note: | + The `gen_ai.system` describes a family of GenAI models with specific model identified + by `gen_ai.request.model` and `gen_ai.response.model` attributes. + The actual GenAI product may differ from the one identified by the client. For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` is set to `openai` based on the instrumentation's best knowledge. @@ -128,6 +131,18 @@ groups: examples: ["[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]"] - id: operation.name stability: experimental - type: string + type: + members: + - id: chat + value: "chat" + brief: 'Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat)' + stability: experimental + - id: text_completion + value: "text_completion" + brief: 'Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions)' + stability: experimental brief: The name of the operation being performed. - examples: ['chat', 'completion'] + note: > + If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic + conventions for specific GenAI system and use system-specific name in the instrumentation. + If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. diff --git a/model/trace/gen-ai.yaml b/model/trace/gen-ai.yaml index 1c2418efab..d036c19755 100644 --- a/model/trace/gen-ai.yaml +++ b/model/trace/gen-ai.yaml @@ -12,6 +12,8 @@ groups: The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + - ref: gen_ai.operation.name + requirement_level: required - ref: gen_ai.request.max_tokens requirement_level: recommended - ref: gen_ai.request.temperature From f17a4bf973d32a0888a8219a408397f8eeac12ed Mon Sep 17 00:00:00 2001 From: jason plumb <75337021+breedx-splk@users.noreply.github.com> Date: Tue, 9 Jul 2024 17:37:04 -0700 Subject: [PATCH 13/23] [chore] Remove SHOULD for compiler name in `process.runtime.name`. (#1221) Co-authored-by: Liudmila Molkova --- docs/attributes-registry/process.md | 2 +- docs/resource/process.md | 2 +- model/registry/process.yaml | 3 +-- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/attributes-registry/process.md b/docs/attributes-registry/process.md index 6522b0ace3..9b47e08949 100644 --- a/docs/attributes-registry/process.md +++ b/docs/attributes-registry/process.md @@ -33,7 +33,7 @@ An operating system process. | `process.real_user.id` | int | The real user ID (RUID) of the process. | `1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `process.real_user.name` | string | The username of the real user of the process. | `operator` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `process.runtime.description` | string | An additional description about the runtime of the process, for example a specific vendor customization of the runtime environment. | `Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `process.runtime.name` | string | The name of the runtime of this process. For compiled native binaries, this SHOULD be the name of the compiler. | `OpenJDK Runtime Environment` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process.runtime.name` | string | The name of the runtime of this process. | `OpenJDK Runtime Environment` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `process.runtime.version` | string | The version of the runtime of this process, as returned by the runtime without modification. | `14.0.2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `process.saved_user.id` | int | The saved user ID (SUID) of the process. | `1002` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `process.saved_user.name` | string | The username of the saved user. | `operator` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/resource/process.md b/docs/resource/process.md index a081022d6f..ff17dfcfbf 100644 --- a/docs/resource/process.md +++ b/docs/resource/process.md @@ -91,7 +91,7 @@ On Windows and other systems where the native format of process commands is a si | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`process.runtime.description`](/docs/attributes-registry/process.md) | string | An additional description about the runtime of the process, for example a specific vendor customization of the runtime environment. | `Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`process.runtime.name`](/docs/attributes-registry/process.md) | string | The name of the runtime of this process. For compiled native binaries, this SHOULD be the name of the compiler. | `OpenJDK Runtime Environment` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.runtime.name`](/docs/attributes-registry/process.md) | string | The name of the runtime of this process. | `OpenJDK Runtime Environment` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`process.runtime.version`](/docs/attributes-registry/process.md) | string | The version of the runtime of this process, as returned by the runtime without modification. | `14.0.2` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/registry/process.yaml b/model/registry/process.yaml index 7cb7451e66..d9c0575ae7 100644 --- a/model/registry/process.yaml +++ b/model/registry/process.yaml @@ -130,8 +130,7 @@ groups: type: string stability: experimental brief: > - The name of the runtime of this process. For compiled native binaries, - this SHOULD be the name of the compiler. + The name of the runtime of this process. examples: ['OpenJDK Runtime Environment'] - id: runtime.version type: string From 0e56677c841b4472001eb2acd6d74598b047ec6f Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 11 Jul 2024 15:25:32 -0700 Subject: [PATCH 14/23] Editorial: mention that Redis `db.namespace` is a string (#1233) --- docs/database/redis.md | 2 +- model/trace/database.yaml | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/database/redis.md b/docs/database/redis.md index bbe41a21c2..564e119af6 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -23,7 +23,7 @@ described on this page. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select). [1] | `0`; `1`; `15` | `Conditionally Required` If and only if it can be captured reliably. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select) (captured as a string). [1] | `0`; `1`; `15` | `Conditionally Required` If and only if it can be captured reliably. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [2] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [4] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [5] | `80`; `8080`; `443` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/model/trace/database.yaml b/model/trace/database.yaml index 24d92636dd..8140688b97 100644 --- a/model/trace/database.yaml +++ b/model/trace/database.yaml @@ -162,7 +162,8 @@ groups: attributes: - ref: db.namespace brief: > - The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select). + The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select) + (captured as a string). requirement_level: conditionally_required: If and only if it can be captured reliably. note: > From 3f936c6a8f2a9141735526977b4d2e562e9d6e64 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 11 Jul 2024 15:45:52 -0700 Subject: [PATCH 15/23] Define sampling relevant attributes for database client spans (#1166) Co-authored-by: Liudmila Molkova --- .chloggen/1166.yaml | 22 ++++++++++++++ docs/database/cassandra.md | 12 +++++++- docs/database/cosmosdb.md | 12 +++++++- docs/database/couchdb.md | 10 ++++++- docs/database/database-spans.md | 11 +++++++ docs/database/elasticsearch.md | 14 ++++++++- docs/database/hbase.md | 11 ++++++- docs/database/mongodb.md | 11 ++++++- docs/database/mssql.md | 12 +++++++- docs/database/redis.md | 11 ++++++- docs/database/sql.md | 9 ++++++ model/trace/database.yaml | 51 +++++++++++++++++++++++++++------ 12 files changed, 170 insertions(+), 16 deletions(-) create mode 100644 .chloggen/1166.yaml diff --git a/.chloggen/1166.yaml b/.chloggen/1166.yaml new file mode 100644 index 0000000000..2202ecc8d1 --- /dev/null +++ b/.chloggen/1166.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: breaking + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: db + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Sampling relevant attributes defined for database client spans + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [ 1019 ] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index fec15f7cf0..3b8837df60 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -10,7 +10,7 @@ The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend a that describe common database operations attributes in addition to the Semantic Conventions described on this page. -`db.system` MUST be set to `"cassandra"`. +`db.system` MUST be set to `"cassandra"` and SHOULD be provided **at span creation time**. ## Attributes @@ -75,6 +75,16 @@ If a parameter has no name and instead is referenced only by index, then `` +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`db.query.text`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `db.cassandra.consistency_level` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 6fa48db887..b6f4330082 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -13,7 +13,7 @@ described on this page. ## Attributes -`db.system` MUST be set to `"cosmosdb"`. +`db.system` MUST be set to `"cosmosdb"` and SHOULD be provided **at span creation time**. Cosmos DB instrumentation includes call-level (public API) surface spans and network spans. Depending on the connection mode (Gateway or Direct), network-level spans may also be created. @@ -76,6 +76,16 @@ If a parameter has no name and instead is referenced only by index, then `` +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`db.query.text`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `db.cosmosdb.connection_mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index 3aa0ad625c..7d33f249b4 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -10,7 +10,7 @@ The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and o that describe common database operations attributes in addition to the Semantic Conventions described on this page. -`db.system` MUST be set to `"couchdb"`. +`db.system` MUST be set to `"couchdb"` and SHOULD be provided **at span creation time**. ## Attributes @@ -43,6 +43,14 @@ described on this page. +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 88093233d8..3a38d4def6 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -142,6 +142,17 @@ If a parameter has no name and instead is referenced only by index, then `` +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`db.query.text`](/docs/attributes-registry/db.md) +* [`db.system`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index d881f79ace..0c6fcb3c98 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -10,7 +10,7 @@ The Semantic Conventions for [Elasticsearch](https://www.elastic.co/) extend and that describe common database operations attributes in addition to the Semantic Conventions described on this page. -`db.system` MUST be set to `"elasticsearch"`. +`db.system` MUST be set to `"elasticsearch"` and SHOULD be provided **at span creation time**. ## Span Name @@ -84,6 +84,18 @@ Even though parameterized query text can potentially have sensitive data, by usi +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`db.query.text`](/docs/attributes-registry/db.md) +* [`http.request.method`](/docs/attributes-registry/http.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) +* [`url.full`](/docs/attributes-registry/url.md) + `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/hbase.md b/docs/database/hbase.md index 24573caae9..6e6419862b 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -10,7 +10,7 @@ The Semantic Conventions for [HBase](https://hbase.apache.org/) extend and overr that describe common database operations attributes in addition to the Semantic Conventions described on this page. -`db.system` MUST be set to `"hbase"`. +`db.system` MUST be set to `"hbase"` and SHOULD be provided **at span creation time**. ## Attributes @@ -50,6 +50,15 @@ For batch operations, if the individual operations are known to have the same op +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index 50ff165787..ff3f18891c 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -10,7 +10,7 @@ The Semantic Conventions for [MongoDB](https://www.mongodb.com/) extend and over that describe common database operations attributes in addition to the Semantic Conventions described on this page. -`db.system` MUST be set to `"mongodb"`. +`db.system` MUST be set to `"mongodb"` and SHOULD be provided **at span creation time**. ## Attributes @@ -48,6 +48,15 @@ For batch operations, if the individual operations are known to have the same co +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 6962223af7..8ea95cbe8a 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -10,7 +10,7 @@ The Semantic Conventions for the *Microsoft SQL Server* extend and override the that describe common database operations attributes in addition to the Semantic Conventions described on this page. -`db.system` MUST be set to `"mssql"`. +`db.system` MUST be set to `"mssql"` and SHOULD be provided **at span creation time**. ## Attributes @@ -65,6 +65,16 @@ If a parameter has no name and instead is referenced only by index, then `` +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`db.query.text`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/redis.md b/docs/database/redis.md index 564e119af6..71ebcf9ee9 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -10,7 +10,7 @@ The Semantic Conventions for [Redis](https://redis.com/) extend and override the that describe common database operations attributes in addition to the Semantic Conventions described on this page. -`db.system` MUST be set to `"redis"`. +`db.system` MUST be set to `"redis"` and SHOULD be provided **at span creation time**. ## Attributes @@ -63,6 +63,15 @@ If a parameter has no name and instead is referenced only by index, then `` +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`db.query.text`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/database/sql.md b/docs/database/sql.md index 524c5878bd..7a2b57f3e0 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -104,6 +104,15 @@ If a parameter has no name and instead is referenced only by index, then `` +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.operation.name`](/docs/attributes-registry/db.md) +* [`db.query.text`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/model/trace/database.yaml b/model/trace/database.yaml index 8140688b97..36f321d03c 100644 --- a/model/trace/database.yaml +++ b/model/trace/database.yaml @@ -1,10 +1,26 @@ groups: - - id: trace.db.common.query + - id: trace.db.common.minimal extends: attributes.db.client.minimal type: attribute_group brief: This group defines the attributes used to perform database client calls. + attributes: + # TODO: add db.system once https://github.com/open-telemetry/build-tools/issues/192 is possible + # - ref: db.system + # sampling_relevant: true + - ref: db.operation.name + sampling_relevant: true + - ref: server.address + sampling_relevant: true + - ref: server.port + sampling_relevant: true + + - id: trace.db.common.query + extends: trace.db.common.minimal + type: attribute_group + brief: This group defines the attributes used to perform database client calls. attributes: - ref: db.query.text + sampling_relevant: true requirement_level: recommended: > Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes @@ -17,11 +33,12 @@ groups: requirement_level: opt_in - id: trace.db.common.query_and_collection - extends: attributes.db.client.minimal + extends: trace.db.common.minimal type: attribute_group brief: This group defines the attributes used to perform database client calls. attributes: - ref: db.query.text + sampling_relevant: true requirement_level: recommended: > SHOULD be collected by default only if there is sanitization that excludes sensitive information. @@ -29,6 +46,7 @@ groups: - ref: db.query.parameter requirement_level: opt_in - ref: db.collection.name + sampling_relevant: true requirement_level: conditionally_required: > If readily available. The collection name MAY be parsed from the query text, @@ -52,9 +70,11 @@ groups: requirement_level: recommended: if and only if `network.peer.address` is set. - ref: db.system + sampling_relevant: true # TODO: Not adding to the minimal because of https://github.com/open-telemetry/build-tools/issues/192 requirement_level: required - ref: db.namespace + sampling_relevant: true requirement_level: conditionally_required: If available. @@ -72,6 +92,7 @@ groups: Attributes for Microsoft SQL Server attributes: - ref: db.namespace + sampling_relevant: true brief: The name of the database, fully qualified within the server address and port. note: When connecting to a default instance, `db.namespace` SHOULD be set to the name of @@ -88,6 +109,7 @@ groups: Attributes for Cassandra attributes: - ref: db.namespace + sampling_relevant: true brief: The Cassandra keyspace name. note: For commands that switch the keyspace, this SHOULD be set to the target keyspace (even if the command fails). examples: ["mykeyspace"] @@ -112,11 +134,12 @@ groups: recommended: if and only if `network.peer.address` is set. - id: db.hbase type: span - extends: attributes.db.client.minimal + extends: trace.db.common.minimal brief: > Attributes for HBase attributes: - ref: db.namespace + sampling_relevant: true brief: The HBase namespace. requirement_level: conditionally_required: If applicable. @@ -126,6 +149,7 @@ groups: instrumentation SHOULD set `db.namespace` value to `default`. examples: ['mynamespace'] - ref: db.collection.name + sampling_relevant: true brief: The HBase table name. requirement_level: conditionally_required: If applicable. @@ -135,11 +159,12 @@ groups: - id: db.couchdb type: span - extends: attributes.db.client.minimal + extends: trace.db.common.minimal brief: > Attributes for CouchDB attributes: - ref: db.operation.name + sampling_relevant: true brief: > The HTTP method + the target REST route. examples: ['GET /{db}/{docid}'] @@ -150,6 +175,7 @@ groups: (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`](https://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid). - ref: db.namespace + sampling_relevant: true requirement_level: conditionally_required: If available. note: "" # overriding the base note @@ -161,6 +187,7 @@ groups: Attributes for Redis attributes: - ref: db.namespace + sampling_relevant: true brief: > The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select) (captured as a string). @@ -176,6 +203,7 @@ groups: For commands that switch the database, this SHOULD be set to the target database (even if the command fails). examples: ["0", "1", "15"] - ref: db.query.text + sampling_relevant: true brief: > The full syntax of the Redis CLI command. examples: ["HMSET myhash field1 'Hello' field2 'World'"] @@ -194,21 +222,24 @@ groups: - id: db.mongodb type: span - extends: attributes.db.client.minimal + extends: trace.db.common.minimal brief: > Attributes for MongoDB attributes: - ref: db.operation.name + sampling_relevant: true brief: > The name of the command being executed. note: > See [MongoDB database commands](https://www.mongodb.com/docs/manual/reference/command/). examples: ['findAndModify', 'getMore', 'update'] - ref: db.collection.name + sampling_relevant: true brief: The MongoDB collection being accessed within the database stated in `db.namespace`. requirement_level: required - ref: db.namespace + sampling_relevant: true brief: The MongoDB database name. requirement_level: conditionally_required: If available. @@ -216,11 +247,12 @@ groups: - id: db.elasticsearch type: span - extends: attributes.db.client.minimal + extends: trace.db.common.minimal brief: > Attributes for Elasticsearch attributes: - ref: http.request.method + sampling_relevant: true requirement_level: required - ref: db.operation.name requirement_level: required @@ -229,9 +261,11 @@ groups: (see the [Elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json)). examples: [ 'search', 'ml.close_job', 'cat.aliases' ] - ref: url.full + sampling_relevant: true requirement_level: required examples: [ 'https://localhost:9200/index/_search?q=user.id:kimchy' ] - ref: db.query.text + sampling_relevant: true requirement_level: recommended: > Should be collected by default for search-type queries and only if there is sanitization that excludes @@ -239,15 +273,15 @@ groups: brief: The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. examples: [ '"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"' ] - ref: db.collection.name + sampling_relevant: true requirement_level: recommended brief: The index or data stream against which the query is executed. note: > The query may target multiple indices or data streams, in which case it SHOULD be a comma separated list of those. If the query doesn't target a specific index, this field MUST NOT be set. examples: [ 'my_index', 'index1, index2' ] - - ref: server.address - - ref: server.port - ref: db.namespace + sampling_relevant: true note: > When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. brief: The name of the Elasticsearch cluster which the client connects to. @@ -342,6 +376,7 @@ groups: requirement_level: conditionally_required: when available - ref: db.namespace + sampling_relevant: true requirement_level: conditionally_required: If available. note: "" # overriding the base note From f79fe6b61438bfa0804df9c254c402fd0d71f42a Mon Sep 17 00:00:00 2001 From: Daniel Jaglowski Date: Thu, 11 Jul 2024 18:10:55 -0500 Subject: [PATCH 16/23] Add 'log.record.original' attribute (#1217) Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Co-authored-by: Liudmila Molkova --- .chloggen/log-original-body.yaml | 22 ++++++++++++++++++++++ docs/attributes-registry/log.md | 11 +++++++---- docs/general/logs.md | 7 +++++-- model/logs/general.yaml | 2 ++ model/registry/log.yaml | 11 +++++++++++ 5 files changed, 47 insertions(+), 6 deletions(-) create mode 100755 .chloggen/log-original-body.yaml diff --git a/.chloggen/log-original-body.yaml b/.chloggen/log-original-body.yaml new file mode 100755 index 0000000000..858bf4242e --- /dev/null +++ b/.chloggen/log-original-body.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: log + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add 'log.record.original' attribute. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1137] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/attributes-registry/log.md b/docs/attributes-registry/log.md index 837a982cb5..7aeff8c921 100644 --- a/docs/attributes-registry/log.md +++ b/docs/attributes-registry/log.md @@ -40,9 +40,12 @@ Attributes for a file to which log was emitted. This document defines the generic attributes that may be used in any Log Record. -| Attribute | Type | Description | Examples | Stability | -| ---------------- | ------ | ------------------------------------------- | ---------------------------- | ---------------------------------------------------------------- | -| `log.record.uid` | string | A unique identifier for the Log Record. [1] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| --------------------- | ------ | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `log.record.original` | string | The complete orignal Log Record. [1] | `77 <86>1 2015-08-06T21:58:59.694Z 192.168.2.133 inactive - - - Something happened`; `[INFO] 8/3/24 12:34:56 Something happened` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `log.record.uid` | string | A unique identifier for the Log Record. [2] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values. +**[1]:** This value MAY be added when processing a Log Record which was originally transmitted as a string or equivalent data type AND the Body field of the Log Record does not contain the same value. (e.g. a syslog or a log record read from a file.) + +**[2]:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values. The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), but other identifiers (e.g. UUID) may be used as needed. diff --git a/docs/general/logs.md b/docs/general/logs.md index 499b719841..b48b379edd 100644 --- a/docs/general/logs.md +++ b/docs/general/logs.md @@ -44,9 +44,12 @@ These attributes may be used for identifying a Log Record. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`log.record.uid`](/docs/attributes-registry/log.md) | string | A unique identifier for the Log Record. [1] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`log.record.original`](/docs/attributes-registry/log.md) | string | The complete orignal Log Record. [1] | `77 <86>1 2015-08-06T21:58:59.694Z 192.168.2.133 inactive - - - Something happened`; `[INFO] 8/3/24 12:34:56 Something happened` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`log.record.uid`](/docs/attributes-registry/log.md) | string | A unique identifier for the Log Record. [2] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values. +**[1]:** This value MAY be added when processing a Log Record which was originally transmitted as a string or equivalent data type AND the Body field of the Log Record does not contain the same value. (e.g. a syslog or a log record read from a file.) + +**[2]:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values. The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), but other identifiers (e.g. UUID) may be used as needed. diff --git a/model/logs/general.yaml b/model/logs/general.yaml index b4afe2c16c..d4835d6982 100644 --- a/model/logs/general.yaml +++ b/model/logs/general.yaml @@ -6,3 +6,5 @@ groups: attributes: - ref: log.record.uid requirement_level: opt_in + - ref: log.record.original + requirement_level: opt_in diff --git a/model/registry/log.yaml b/model/registry/log.yaml index b26870a696..bc18100451 100644 --- a/model/registry/log.yaml +++ b/model/registry/log.yaml @@ -70,3 +70,14 @@ groups: The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), but other identifiers (e.g. UUID) may be used as needed. examples: ["01ARZ3NDEKTSV4RRFFQ69G5FAV"] + - id: original + type: string + stability: experimental + brief: > + The complete orignal Log Record. + note: > + This value MAY be added when processing a Log Record which was originally transmitted as a string or equivalent data type AND + the Body field of the Log Record does not contain the same value. (e.g. a syslog or a log record read from a file.) + examples: + - "77 <86>1 2015-08-06T21:58:59.694Z 192.168.2.133 inactive - - - Something happened" + - "[INFO] 8/3/24 12:34:56 Something happened" From 4e7c42ee8e4c3a39a899c4c85c64df28cd543f78 Mon Sep 17 00:00:00 2001 From: Alexander Wert Date: Mon, 15 Jul 2024 11:58:37 +0200 Subject: [PATCH 17/23] Update build-tools version to 0.25.0 and add `display_name` to all registry attribute groups (#985) Signed-off-by: Alexander Wert --- CONTRIBUTING.md | 2 +- Makefile | 2 +- docs/attributes-registry/android.md | 6 +- docs/attributes-registry/aspnetcore.md | 2 +- docs/attributes-registry/aws.md | 28 +++---- docs/attributes-registry/container.md | 6 +- docs/attributes-registry/db.md | 44 +++++----- docs/attributes-registry/dns.md | 2 +- docs/attributes-registry/enduser.md | 2 +- docs/attributes-registry/faas.md | 2 +- docs/attributes-registry/gcp.md | 12 +-- docs/attributes-registry/gen-ai.md | 8 +- docs/attributes-registry/http.md | 6 +- docs/attributes-registry/ios.md | 2 +- docs/attributes-registry/jvm.md | 2 +- docs/attributes-registry/k8s.md | 8 +- docs/attributes-registry/log.md | 8 +- docs/attributes-registry/messaging.md | 58 +++++++------- docs/attributes-registry/network.md | 6 +- docs/attributes-registry/oci.md | 2 +- docs/attributes-registry/os.md | 2 +- docs/attributes-registry/otel.md | 24 +++--- docs/attributes-registry/process.md | 6 +- docs/attributes-registry/rpc.md | 8 +- docs/attributes-registry/system.md | 80 +++++++++---------- docs/attributes-registry/user-agent.md | 2 +- docs/attributes-registry/v8js.md | 2 +- docs/attributes-registry/webengine.md | 2 +- internal/tools/schema_check.sh | 2 +- model/README.md | 4 +- model/registry/android.yaml | 1 + model/registry/aspnetcore.yaml | 1 + model/registry/aws.yaml | 7 ++ model/registry/browser.yaml | 1 + model/registry/client.yaml | 1 + model/registry/cloud.yaml | 1 + model/registry/cloudevents.yaml | 1 + model/registry/code.yaml | 1 + model/registry/container.yaml | 1 + model/registry/cpu.yaml | 1 + model/registry/db.yaml | 4 + model/registry/deployment.yaml | 1 + model/registry/deprecated/android.yaml | 1 + model/registry/deprecated/container.yaml | 1 + model/registry/deprecated/db.yaml | 2 + model/registry/deprecated/enduser.yaml | 1 + model/registry/deprecated/gen-ai.yaml | 1 + model/registry/deprecated/http.yaml | 1 + model/registry/deprecated/ios.yaml | 1 + model/registry/deprecated/k8s.yaml | 1 + model/registry/deprecated/messaging.yaml | 1 + model/registry/deprecated/network.yaml | 1 + model/registry/deprecated/otel.yaml | 1 + model/registry/deprecated/process.yaml | 1 + model/registry/deprecated/rpc.yaml | 1 + model/registry/deprecated/system.yaml | 1 + model/registry/destination.yaml | 1 + model/registry/device.yaml | 1 + model/registry/disk.yaml | 1 + model/registry/dns.yaml | 1 + model/registry/error.yaml | 1 + model/registry/event.yaml | 1 + model/registry/exception.yaml | 1 + model/registry/faas.yaml | 1 + model/registry/feature-flag.yaml | 1 + model/registry/file.yaml | 1 + model/registry/gcp.yaml | 4 + model/registry/gen-ai.yaml | 1 + model/registry/go.yaml | 1 + model/registry/graphql.yaml | 1 + model/registry/heroku.yaml | 1 + model/registry/host.yaml | 1 + model/registry/http.yaml | 1 + model/registry/jvm.yaml | 1 + model/registry/k8s.yaml | 1 + model/registry/log.yaml | 3 + model/registry/messaging.yaml | 7 ++ model/registry/network.yaml | 1 + model/registry/oci.yaml | 1 + model/registry/opentracing.yaml | 1 + model/registry/os.yaml | 1 + model/registry/otel.yaml | 2 + model/registry/peer.yaml | 1 + model/registry/process.yaml | 1 + model/registry/rpc.yaml | 1 + model/registry/server.yaml | 1 + model/registry/service.yaml | 1 + model/registry/session.yaml | 1 + model/registry/signalr.yaml | 1 + model/registry/source.yaml | 1 + model/registry/system.yaml | 7 ++ model/registry/telemetry.yaml | 1 + model/registry/thread.yaml | 1 + model/registry/tls.yaml | 1 + model/registry/url.yaml | 1 + model/registry/user-agent.yaml | 1 + model/registry/user.yaml | 1 + model/registry/v8js.yaml | 1 + model/registry/webengine.yaml | 1 + .../registry/markdown/attribute_macros.j2 | 7 ++ .../markdown/attribute_namespace.md.j2 | 21 +++-- 101 files changed, 289 insertions(+), 176 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3e8f596ce..059ede01d1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -83,7 +83,7 @@ environment configured: ### 1. Modify the YAML model Refer to the -[Semantic Convention YAML Language](https://github.com/open-telemetry/build-tools/blob/v0.24.0/semantic-conventions/syntax.md) +[Semantic Convention YAML Language](https://github.com/open-telemetry/build-tools/blob/v0.25.0/semantic-conventions/syntax.md) to learn how to make changes to the YAML files. #### Schema files diff --git a/Makefile b/Makefile index b2af508988..4f16ea2e7b 100644 --- a/Makefile +++ b/Makefile @@ -13,7 +13,7 @@ CHLOGGEN_CONFIG := .chloggen/config.yaml # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates # Keep links in model/README.md and .vscode/settings.json in sync! -SEMCONVGEN_VERSION=0.24.0 +SEMCONVGEN_VERSION=0.25.0 WEAVER_VERSION=0.5.0 # From where to resolve the containers (e.g. "otel/weaver"). diff --git a/docs/attributes-registry/android.md b/docs/attributes-registry/android.md index c540e60cea..a8c442da77 100644 --- a/docs/attributes-registry/android.md +++ b/docs/attributes-registry/android.md @@ -6,8 +6,8 @@ # Android -- [Android](#android-attributes) -- [Android Deprecated](#android-deprecated-attributes) +- [Android Attributes](#android-attributes) +- [Deprecated Android Attributes](#deprecated-android-attributes) ## Android Attributes @@ -17,7 +17,7 @@ The Android platform on which the Android application is running. | ---------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------- | | `android.os.api_level` | string | Uniquely identifies the framework API revision offered by a version (`os.version`) of the android operating system. More information can be found [here](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels). | `33`; `32` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Android Deprecated Attributes +## Deprecated Android Attributes This document defines attributes that represents an occurrence of a lifecycle transition on the Android platform. diff --git a/docs/attributes-registry/aspnetcore.md b/docs/attributes-registry/aspnetcore.md index 1fe1a2ad74..941c86fcb0 100644 --- a/docs/attributes-registry/aspnetcore.md +++ b/docs/attributes-registry/aspnetcore.md @@ -6,7 +6,7 @@ # Aspnetcore -## Aspnetcore Attributes +## ASP.NET Core Attributes ASP.NET Core attributes diff --git a/docs/attributes-registry/aws.md b/docs/attributes-registry/aws.md index fa4cf4deac..4d36c2e3c8 100644 --- a/docs/attributes-registry/aws.md +++ b/docs/attributes-registry/aws.md @@ -6,15 +6,15 @@ # AWS -- [Aws](#aws-attributes) -- [Aws Dynamodb](#aws-dynamodb-attributes) -- [Aws Ecs](#aws-ecs-attributes) -- [Aws Eks](#aws-eks-attributes) -- [Aws Lambda](#aws-lambda-attributes) -- [Aws Log](#aws-log-attributes) -- [Aws S3](#aws-s3-attributes) +- [General AWS Attributes](#general-aws-attributes) +- [Amazon DynamoDB Attributes](#amazon-dynamodb-attributes) +- [Amazon ECS Attributes](#amazon-ecs-attributes) +- [Amazon EKS Attributes](#amazon-eks-attributes) +- [Amazon Lambda Attributes](#amazon-lambda-attributes) +- [Amazon Logs Attributes](#amazon-logs-attributes) +- [Amazon S3 Attributes](#amazon-s3-attributes) -## AWS Attributes +## General AWS Attributes This document defines generic attributes for AWS services. @@ -22,7 +22,7 @@ This document defines generic attributes for AWS services. | ---------------- | ------ | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------- | | `aws.request_id` | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## AWS DynamoDB Attributes +## Amazon DynamoDB Attributes This document defines attributes for AWS DynamoDB. @@ -51,7 +51,7 @@ This document defines attributes for AWS DynamoDB. | `aws.dynamodb.table_names` | string[] | The keys in the `RequestItems` object field. | `["Users", "Cats"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `aws.dynamodb.total_segments` | int | The value of the `TotalSegments` request parameter. | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## AWS ECS Attributes +## Amazon ECS Attributes This document defines attributes for AWS Elastic Container Service (ECS). @@ -72,7 +72,7 @@ This document defines attributes for AWS Elastic Container Service (ECS). | `ec2` | ec2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `fargate` | fargate | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## AWS EKS Attributes +## Amazon EKS Attributes This document defines attributes for AWS Elastic Kubernetes Service (EKS). @@ -80,7 +80,7 @@ This document defines attributes for AWS Elastic Kubernetes Service (EKS). | --------------------- | ------ | -------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------- | | `aws.eks.cluster.arn` | string | The ARN of an EKS cluster. | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## AWS Lambda Attributes +## Amazon Lambda Attributes This document defines attributes for AWS Lambda. @@ -90,7 +90,7 @@ This document defines attributes for AWS Lambda. **[1]:** This may be different from `cloud.resource_id` if an alias is involved. -## AWS Log Attributes +## Amazon Logs Attributes This document defines attributes for AWS Logs. @@ -107,7 +107,7 @@ This document defines attributes for AWS Logs. **[4]:** See the [log stream ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). One log group can contain several log streams, so these ARNs necessarily identify both a log group and a log stream. -## AWS S3 Attributes +## Amazon S3 Attributes This document defines attributes for AWS S3. diff --git a/docs/attributes-registry/container.md b/docs/attributes-registry/container.md index fdca43d789..4aef8d3f91 100644 --- a/docs/attributes-registry/container.md +++ b/docs/attributes-registry/container.md @@ -6,8 +6,8 @@ # Container -- [Container](#container-attributes) -- [Container Deprecated](#container-deprecated-attributes) +- [Container Attributes](#container-attributes) +- [Deprecated Container Attributes](#deprecated-container-attributes) ## Container Attributes @@ -35,7 +35,7 @@ The ID is assigned by the container runtime and can vary in different environmen **[3]:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field. -## Container Deprecated Attributes +## Deprecated Container Attributes Describes deprecated container attributes. diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index db78b93f6b..066ca70bac 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -6,14 +6,14 @@ # Db -- [Db](#db-attributes) -- [Db Cassandra](#db-cassandra-attributes) -- [Db Cosmosdb](#db-cosmosdb-attributes) -- [Db Deprecated](#db-deprecated-attributes) -- [Db Elasticsearch](#db-elasticsearch-attributes) -- [Db Metrics Deprecated](#db-metrics-deprecated-attributes) +- [General Database Attributes](#general-database-attributes) +- [Cassandra Attributes](#cassandra-attributes) +- [Azure Cosmos DB Attributes](#azure-cosmos-db-attributes) +- [Elasticsearch Attributes](#elasticsearch-attributes) +- [Deprecated Database Attributes](#deprecated-database-attributes) +- [Deprecated Database Metrics](#deprecated-database-metrics) -## Db Attributes +## General Database Attributes This group defines the attributes used to describe telemetry in the context of databases. @@ -118,7 +118,7 @@ Even though parameterized query text can potentially have sensitive data, by usi | `trino` | Trino | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `vertica` | Vertica | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Db Cassandra Attributes +## Cassandra Attributes This group defines attributes for Cassandra. @@ -147,7 +147,7 @@ This group defines attributes for Cassandra. | `three` | three | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `two` | two | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Db CosmosDB Attributes +## Azure Cosmos DB Attributes This group defines attributes for Azure Cosmos DB. @@ -188,7 +188,18 @@ This group defines attributes for Azure Cosmos DB. | `Replace` | replace | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `Upsert` | upsert | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Db Deprecated Attributes +## Elasticsearch Attributes + +This group defines attributes for Elasticsearch. + +| Attribute | Type | Description | Examples | Stability | +| ----------------------------------- | ------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [8] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[8]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names. + +## Deprecated Database Attributes "Describes deprecated db attributes." @@ -209,18 +220,7 @@ This group defines attributes for Azure Cosmos DB. | `db.statement` | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.query.text`. | | `db.user` | string | Deprecated, no replacement at this time. | `readonly_user`; `reporting_user` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
No replacement at this time. | -## Db Elasticsearch Attributes - -This group defines attributes for Elasticsearch. - -| Attribute | Type | Description | Examples | Stability | -| ----------------------------------- | ------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [8] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[8]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names. - -## Db Metrics Deprecated Attributes +## Deprecated Database Metrics "Describes deprecated db metrics attributes." diff --git a/docs/attributes-registry/dns.md b/docs/attributes-registry/dns.md index 6345d59240..a03b3cef57 100644 --- a/docs/attributes-registry/dns.md +++ b/docs/attributes-registry/dns.md @@ -6,7 +6,7 @@ # Dns -## Dns Attributes +## DNS Attributes This document defines the shared attributes used to report a DNS query. diff --git a/docs/attributes-registry/enduser.md b/docs/attributes-registry/enduser.md index 66ba5a0d1e..db2d7a5835 100644 --- a/docs/attributes-registry/enduser.md +++ b/docs/attributes-registry/enduser.md @@ -6,7 +6,7 @@ # Enduser -## Enduser Deprecated Attributes +## Deprecated End User Attributes Describes deprecated enduser attributes. Complete enduser namespace has been deprecated diff --git a/docs/attributes-registry/faas.md b/docs/attributes-registry/faas.md index 26a1200ece..6279999b71 100644 --- a/docs/attributes-registry/faas.md +++ b/docs/attributes-registry/faas.md @@ -6,7 +6,7 @@ # Faas -## Faas Attributes +## Function as a Service Attributes FaaS attributes diff --git a/docs/attributes-registry/gcp.md b/docs/attributes-registry/gcp.md index cade703150..04f6f981bf 100644 --- a/docs/attributes-registry/gcp.md +++ b/docs/attributes-registry/gcp.md @@ -6,10 +6,10 @@ # GCP -- [Gcp](#gcp-attributes) -- [Gcp Client](#gcp-client-attributes) -- [Gcp Cloud Run](#gcp-cloud-run-attributes) -- [Gcp Gce](#gcp-gce-attributes) +- [GCP Attributes](#gcp-attributes) +- [GCP Client Attributes](#gcp-client-attributes) +- [GCP - Google Cloud Run Attributes](#gcp---google-cloud-run-attributes) +- [GCP - Google Compute Engine (GCE) Attributes](#gcp---google-compute-engine-gce-attributes) ## GCP Attributes @@ -28,7 +28,7 @@ Attributes for Google Cloud client libraries. **[1]:** Intended to be a stable identifier for Google Cloud client libraries that is uniform across implementation languages. The value should be derived from the canonical service domain for the service; for example, 'foo.googleapis.com' should result in a value of 'foo'. -## GCP Cloud Run Attributes +## GCP - Google Cloud Run Attributes This document defines attributes for Google Cloud Run. @@ -37,7 +37,7 @@ This document defines attributes for Google Cloud Run. | `gcp.cloud_run.job.execution` | string | The name of the Cloud Run [execution](https://cloud.google.com/run/docs/managing/job-executions) being run for the Job, as set by the [`CLOUD_RUN_EXECUTION`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `job-name-xxxx`; `sample-job-mdw84` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gcp.cloud_run.job.task_index` | int | The index for a task within an execution as provided by the [`CLOUD_RUN_TASK_INDEX`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `0`; `1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## GCP GCE Attributes +## GCP - Google Compute Engine (GCE) Attributes This document defines attributes for Google Compute Engine (GCE). diff --git a/docs/attributes-registry/gen-ai.md b/docs/attributes-registry/gen-ai.md index a9c090a32b..d136ebf575 100644 --- a/docs/attributes-registry/gen-ai.md +++ b/docs/attributes-registry/gen-ai.md @@ -6,10 +6,10 @@ # Gen AI -- [Gen Ai](#gen-ai-attributes) -- [Gen Ai Deprecated](#gen-ai-deprecated-attributes) +- [GenAI Attributes](#genai-attributes) +- [Deprecated GenAI Attributes](#deprecated-genai-attributes) -## Gen AI Attributes +## GenAI Attributes This document defines the attributes used to describe telemetry in the context of Generative Artificial Intelligence (GenAI) Models requests and responses. @@ -73,7 +73,7 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. | `input` | Input tokens (prompt, input, etc.) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `output` | Output tokens (completion, response, etc.) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Gen AI Deprecated Attributes +## Deprecated GenAI Attributes Describes deprecated `gen_ai` attributes. diff --git a/docs/attributes-registry/http.md b/docs/attributes-registry/http.md index 7d33288aef..069666a943 100644 --- a/docs/attributes-registry/http.md +++ b/docs/attributes-registry/http.md @@ -6,8 +6,8 @@ # HTTP -- [Http](#http-attributes) -- [Http Deprecated](#http-deprecated-attributes) +- [HTTP Attributes](#http-attributes) +- [Deprecated HTTP Attributes](#deprecated-http-attributes) ## HTTP Attributes @@ -78,7 +78,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -## HTTP Deprecated Attributes +## Deprecated HTTP Attributes Describes deprecated HTTP attributes. diff --git a/docs/attributes-registry/ios.md b/docs/attributes-registry/ios.md index f15cf13d6a..a8891cdcbd 100644 --- a/docs/attributes-registry/ios.md +++ b/docs/attributes-registry/ios.md @@ -6,7 +6,7 @@ # iOS -## iOS Deprecated Attributes +## Deprecated iOS Attributes The iOS platform on which the iOS application is running. diff --git a/docs/attributes-registry/jvm.md b/docs/attributes-registry/jvm.md index 70f08089d7..75f1f3093a 100644 --- a/docs/attributes-registry/jvm.md +++ b/docs/attributes-registry/jvm.md @@ -6,7 +6,7 @@ # JVM -## JVM Attributes +## Java Virtual Machine (JVM) Attributes This document defines Java Virtual machine related attributes. diff --git a/docs/attributes-registry/k8s.md b/docs/attributes-registry/k8s.md index b9bc225333..34d2e64c88 100644 --- a/docs/attributes-registry/k8s.md +++ b/docs/attributes-registry/k8s.md @@ -6,10 +6,10 @@ # K8s -- [K8s](#k8s-attributes) -- [K8s Deprecated](#k8s-deprecated-attributes) +- [Kubernetes Attributes](#kubernetes-attributes) +- [Deprecated Kubernetes Attributes](#deprecated-kubernetes-attributes) -## K8s Attributes +## Kubernetes Attributes Kubernetes resource attributes. @@ -63,7 +63,7 @@ Which states: Therefore, UIDs between clusters should be extremely unlikely to conflict. -## K8s Deprecated Attributes +## Deprecated Kubernetes Attributes Describes deprecated k8s attributes. diff --git a/docs/attributes-registry/log.md b/docs/attributes-registry/log.md index 7aeff8c921..c24c22b1ac 100644 --- a/docs/attributes-registry/log.md +++ b/docs/attributes-registry/log.md @@ -6,11 +6,11 @@ # Log -- [Log](#log-attributes) -- [Log File](#log-file-attributes) -- [Log Record](#log-record-attributes) +- [General Log Attributes](#general-log-attributes) +- [Log File Attributes](#log-file-attributes) +- [Log Record Attributes](#log-record-attributes) -## Log Attributes +## General Log Attributes This document defines log attributes diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index dd69d0c13e..cf7a11b0b1 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -6,16 +6,16 @@ # Messaging -- [Messaging](#messaging-attributes) -- [Messaging Deprecated](#messaging-deprecated-attributes) -- [Messaging Eventhubs](#messaging-eventhubs-attributes) -- [Messaging Gcp Pubsub](#messaging-gcp-pubsub-attributes) -- [Messaging Kafka](#messaging-kafka-attributes) -- [Messaging Rabbitmq](#messaging-rabbitmq-attributes) -- [Messaging Rocketmq](#messaging-rocketmq-attributes) -- [Messaging Servicebus](#messaging-servicebus-attributes) +- [General Messaging Attributes](#general-messaging-attributes) +- [Azure Event Hubs Attributes](#azure-event-hubs-attributes) +- [GCP Pub/Sub Attributes](#gcp-pubsub-attributes) +- [Kafka Attributes](#kafka-attributes) +- [RabbitMQ Attributes](#rabbitmq-attributes) +- [RocketMQ Attributes](#rocketmq-attributes) +- [Azure Service Bus Attributes](#azure-service-bus-attributes) +- [Deprecated Messaging Attributes](#deprecated-messaging-attributes) -## Messaging Attributes +## General Messaging Attributes Attributes describing telemetry around messaging systems and messaging activities. @@ -91,21 +91,7 @@ size should be used. | `rocketmq` | Apache RocketMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `servicebus` | Azure Service Bus | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Messaging Deprecated Attributes - -Describes deprecated messaging attributes. - -| Attribute | Type | Description | Examples | Stability | -| ---------------------------------------------------- | ------ | ----------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `messaging.client_id` | string | Deprecated, use `messaging.client.id` instead. | `client-5`; `myhost@8742@s8083jm` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.client.id`. | -| `messaging.eventhubs.consumer.group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `$Default` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name`. | -| `messaging.kafka.consumer.group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `my-group` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name`. | -| `messaging.kafka.destination.partition` | int | Deprecated, use `messaging.destination.partition.id` instead. | `2` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.destination.partition.id`. | -| `messaging.operation` | string | Deprecated, use `messaging.operation.type` instead. | `publish`; `create`; `process` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.operation.type`. | -| `messaging.rocketmq.client_group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `myConsumerGroup` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name` on the consumer spans. No replacement for producer spans. | -| `messaging.servicebus.destination.subscription_name` | string | Deprecated, use `messaging.servicebus.destination.subscription_name` instead. | `subscription-a` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.servicebus.destination.subscription_name`. | - -## Messaging Eventhubs Attributes +## Azure Event Hubs Attributes This group describes attributes specific to Azure Event Hubs. @@ -113,7 +99,7 @@ This group describes attributes specific to Azure Event Hubs. | ------------------------------------------- | ---- | -------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------- | | `messaging.eventhubs.message.enqueued_time` | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Messaging GCP Pubsub Attributes +## GCP Pub/Sub Attributes This group describes attributes specific to GCP Pub/Sub. @@ -124,7 +110,7 @@ This group describes attributes specific to GCP Pub/Sub. | `messaging.gcp_pubsub.message.delivery_attempt` | int | The delivery attempt for a given message. | `2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.gcp_pubsub.message.ordering_key` | string | The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. | `ordering_key` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Messaging Kafka Attributes +## Kafka Attributes This group describes attributes specific to Apache Kafka. @@ -136,7 +122,7 @@ This group describes attributes specific to Apache Kafka. **[11]:** If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value. -## Messaging RabbitMQ Attributes +## RabbitMQ Attributes This group describes attributes specific to RabbitMQ. @@ -145,7 +131,7 @@ This group describes attributes specific to RabbitMQ. | `messaging.rabbitmq.destination.routing_key` | string | RabbitMQ message routing key. | `myKey` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.rabbitmq.message.delivery_tag` | int | RabbitMQ message delivery tag | `123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Messaging RocketMQ Attributes +## RocketMQ Attributes This group describes attributes specific to RocketMQ. @@ -176,7 +162,7 @@ This group describes attributes specific to RocketMQ. | `normal` | Normal message | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `transaction` | Transaction message | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Messaging Servicebus Attributes +## Azure Service Bus Attributes This group describes attributes specific to Azure Service Bus. @@ -194,3 +180,17 @@ This group describes attributes specific to Azure Service Bus. | `complete` | Message is completed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `dead_letter` | Message is sent to dead letter queue | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `defer` | Message is deferred | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Deprecated Messaging Attributes + +Describes deprecated messaging attributes. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------------------------------------- | ------ | ----------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `messaging.client_id` | string | Deprecated, use `messaging.client.id` instead. | `client-5`; `myhost@8742@s8083jm` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.client.id`. | +| `messaging.eventhubs.consumer.group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `$Default` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name`. | +| `messaging.kafka.consumer.group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `my-group` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name`. | +| `messaging.kafka.destination.partition` | int | Deprecated, use `messaging.destination.partition.id` instead. | `2` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.destination.partition.id`. | +| `messaging.operation` | string | Deprecated, use `messaging.operation.type` instead. | `publish`; `create`; `process` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.operation.type`. | +| `messaging.rocketmq.client_group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `myConsumerGroup` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name` on the consumer spans. No replacement for producer spans. | +| `messaging.servicebus.destination.subscription_name` | string | Deprecated, use `messaging.servicebus.destination.subscription_name` instead. | `subscription-a` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.servicebus.destination.subscription_name`. | diff --git a/docs/attributes-registry/network.md b/docs/attributes-registry/network.md index 54bf6099f8..1d1e742e6b 100644 --- a/docs/attributes-registry/network.md +++ b/docs/attributes-registry/network.md @@ -6,8 +6,8 @@ # Network -- [Network](#network-attributes) -- [Network Deprecated](#network-deprecated-attributes) +- [Network Attributes](#network-attributes) +- [Deprecated Network Attributes](#deprecated-network-attributes) ## Network Attributes @@ -102,7 +102,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -## Network Deprecated Attributes +## Deprecated Network Attributes These attributes may be used for any network related operation. diff --git a/docs/attributes-registry/oci.md b/docs/attributes-registry/oci.md index 6a2aa64c15..c528a50fcb 100644 --- a/docs/attributes-registry/oci.md +++ b/docs/attributes-registry/oci.md @@ -6,7 +6,7 @@ # OCI -## OCI Manifest Attributes +## Open Container Initiative (OCI) Attributes An OCI image manifest. diff --git a/docs/attributes-registry/os.md b/docs/attributes-registry/os.md index 8785622356..a5b4f44ce8 100644 --- a/docs/attributes-registry/os.md +++ b/docs/attributes-registry/os.md @@ -6,7 +6,7 @@ # OS -## OS Attributes +## Operating System Attributes The operating system (OS) on which the process represented by this resource is running. diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md index 5ac726e13d..07ed204dc1 100644 --- a/docs/attributes-registry/otel.md +++ b/docs/attributes-registry/otel.md @@ -6,9 +6,9 @@ # OTel -- [Otel](#otel-attributes) -- [Otel Library Deprecated](#otel-library-deprecated-attributes) -- [Otel Scope](#otel-scope-attributes) +- [OTel Attributes](#otel-attributes) +- [OTel Scope Attributes](#otel-scope-attributes) +- [Deprecated OTel Library Attributes](#deprecated-otel-library-attributes) ## OTel Attributes @@ -26,15 +26,6 @@ Attributes reserved for OpenTelemetry | `ERROR` | The operation contains an error. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `OK` | The operation has been validated by an Application developer or Operator to have completed successfully. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -## OTel Library Deprecated Attributes - -Describes deprecated otel.library attributes. - -| Attribute | Type | Description | Examples | Stability | -| ---------------------- | ------ | ----------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------ | -| `otel.library.name` | string | | `io.opentelemetry.contrib.mongodb` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
use the `otel.scope.name` attribute. | -| `otel.library.version` | string | | `1.0.0` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
use the `otel.scope.version` attribute. | - ## OTel Scope Attributes Attributes used by non-OTLP exporters to represent OpenTelemetry Scope's concepts. @@ -43,3 +34,12 @@ Attributes used by non-OTLP exporters to represent OpenTelemetry Scope's concept | -------------------- | ------ | ------------------------------------------------------------------------------------ | ---------------------------------- | ---------------------------------------------------------- | | `otel.scope.name` | string | The name of the instrumentation scope - (`InstrumentationScope.Name` in OTLP). | `io.opentelemetry.contrib.mongodb` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `otel.scope.version` | string | The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). | `1.0.0` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +## Deprecated OTel Library Attributes + +Describes deprecated otel.library attributes. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------- | ------ | ----------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------ | +| `otel.library.name` | string | | `io.opentelemetry.contrib.mongodb` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
use the `otel.scope.name` attribute. | +| `otel.library.version` | string | | `1.0.0` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
use the `otel.scope.version` attribute. | diff --git a/docs/attributes-registry/process.md b/docs/attributes-registry/process.md index 9b47e08949..922286f11d 100644 --- a/docs/attributes-registry/process.md +++ b/docs/attributes-registry/process.md @@ -6,8 +6,8 @@ # Process -- [Process](#process-attributes) -- [Process Deprecated](#process-deprecated-attributes) +- [Process Attributes](#process-attributes) +- [Deprecated Process Attributes](#deprecated-process-attributes) ## Process Attributes @@ -58,7 +58,7 @@ An operating system process. | `major` | major | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `minor` | minor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Process Deprecated Attributes +## Deprecated Process Attributes Deprecated process attributes. diff --git a/docs/attributes-registry/rpc.md b/docs/attributes-registry/rpc.md index 561e7c27bc..9c6088a1ce 100644 --- a/docs/attributes-registry/rpc.md +++ b/docs/attributes-registry/rpc.md @@ -6,10 +6,10 @@ # RPC -- [Rpc](#rpc-attributes) -- [Rpc Deprecated](#rpc-deprecated-attributes) +- [Remote Procedure Call (RPC) Attributes](#remote-procedure-call-rpc-attributes) +- [Deprecated RPC Attributes](#deprecated-rpc-attributes) -## RPC Attributes +## Remote Procedure Call (RPC) Attributes This document defines attributes for remote procedure calls. @@ -107,7 +107,7 @@ This document defines attributes for remote procedure calls. | `grpc` | gRPC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `java_rmi` | Java RMI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## RPC Deprecated Attributes +## Deprecated RPC Attributes Deprecated rpc message attributes. diff --git a/docs/attributes-registry/system.md b/docs/attributes-registry/system.md index c504f989f9..60871019ba 100644 --- a/docs/attributes-registry/system.md +++ b/docs/attributes-registry/system.md @@ -6,16 +6,16 @@ # System -- [System](#system-attributes) -- [System Cpu](#system-cpu-attributes) -- [System Deprecated](#system-deprecated-attributes) -- [System Filesystem](#system-filesystem-attributes) -- [System Memory](#system-memory-attributes) -- [System Network](#system-network-attributes) -- [System Paging](#system-paging-attributes) -- [System Process](#system-process-attributes) +- [General System Attributes](#general-system-attributes) +- [System CPU Attributes](#system-cpu-attributes) +- [Filesystem Attributes](#filesystem-attributes) +- [System Memory Attributes](#system-memory-attributes) +- [System Network Attributes](#system-network-attributes) +- [System Paging Attributes](#system-paging-attributes) +- [System Process Attributes](#system-process-attributes) +- [Deprecated System Attributes](#deprecated-system-attributes) -## System Attributes +## General System Attributes Describes System attributes @@ -31,37 +31,7 @@ Describes System CPU attributes | --------------------------- | ---- | ------------------------------- | -------- | ---------------------------------------------------------------- | | `system.cpu.logical_number` | int | The logical CPU number [0..n-1] | `1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## System Deprecated Attributes - -Deprecated system attributes. - -| Attribute | Type | Description | Examples | Stability | -| ------------------------- | ------ | ------------------------------------------------ | ------------------- | --------------------------------------------------------------------------------------------------- | -| `system.cpu.state` | string | Deprecated, use `cpu.mode` instead. | `idle`; `interrupt` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `cpu.mode` | -| `system.processes.status` | string | Deprecated, use `system.process.status` instead. | `running` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `system.process.status`. | - -`system.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -| ----------- | ----------- | ---------------------------------------------------------------- | -| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -`system.processes.status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -| ---------- | ----------- | ---------------------------------------------------------------- | -| `defunct` | defunct | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `running` | running | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `sleeping` | sleeping | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `stopped` | stopped | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -## System Filesystem Attributes +## Filesystem Attributes Describes Filesystem attributes @@ -181,3 +151,33 @@ Describes System Process attributes | `running` | running | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `sleeping` | sleeping | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `stopped` | stopped | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Deprecated System Attributes + +Deprecated system attributes. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------- | ------ | ------------------------------------------------ | ------------------- | --------------------------------------------------------------------------------------------------- | +| `system.cpu.state` | string | Deprecated, use `cpu.mode` instead. | `idle`; `interrupt` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `cpu.mode` | +| `system.processes.status` | string | Deprecated, use `system.process.status` instead. | `running` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `system.process.status`. | + +`system.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ----------- | ----------- | ---------------------------------------------------------------- | +| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`system.processes.status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ---------- | ----------- | ---------------------------------------------------------------- | +| `defunct` | defunct | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `running` | running | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `sleeping` | sleeping | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `stopped` | stopped | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md index 34b0c71f89..b7a10cd630 100644 --- a/docs/attributes-registry/user-agent.md +++ b/docs/attributes-registry/user-agent.md @@ -6,7 +6,7 @@ # User Agent -## User Agent Attributes +## User-agent Attributes Describes user-agent attributes. diff --git a/docs/attributes-registry/v8js.md b/docs/attributes-registry/v8js.md index 2e2bf3fec3..a8ae0bff7a 100644 --- a/docs/attributes-registry/v8js.md +++ b/docs/attributes-registry/v8js.md @@ -6,7 +6,7 @@ # V8js -## V8js Attributes +## V8 JS Attributes Describes V8 JS Engine Runtime related attributes. diff --git a/docs/attributes-registry/webengine.md b/docs/attributes-registry/webengine.md index be5955444e..1cb10ac3fb 100644 --- a/docs/attributes-registry/webengine.md +++ b/docs/attributes-registry/webengine.md @@ -6,7 +6,7 @@ # Webengine -## Webengine Attributes +## Web Engine Attributes This document defines the attributes used to describe the packaged software running the application code. diff --git a/internal/tools/schema_check.sh b/internal/tools/schema_check.sh index 68883941b1..779fd957e8 100755 --- a/internal/tools/schema_check.sh +++ b/internal/tools/schema_check.sh @@ -6,7 +6,7 @@ set -e -BUILD_TOOL_SCHEMAS_VERSION=0.24.0 +BUILD_TOOL_SCHEMAS_VERSION=0.25.0 # List of versions that do not require or have a schema. declare -a skip_versions=("1.0.0" "1.0.1" "1.1.0" "1.2.0" "1.3.0" "1.6.0") diff --git a/model/README.md b/model/README.md index 012b4f4ed7..ec76e3f883 100644 --- a/model/README.md +++ b/model/README.md @@ -14,12 +14,12 @@ Semantic conventions for the spec MUST adhere to the [attribute requirement level](../docs/general/attribute-requirement-level.md), and [metric requirement level](../docs/general/metric-requirement-level.md) conventions. -Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.24.0/semantic-conventions/syntax.md) +Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.25.0/semantic-conventions/syntax.md) for how to write the YAML files for semantic conventions and what the YAML properties mean. A schema file for VS code is configured in the `/.vscode/settings.json` of this repository, enabling auto-completion and additional checks. Refer to -[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.24.0/semantic-conventions/README.md) for what extension you need. +[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.25.0/semantic-conventions/README.md) for what extension you need. ## Generating markdown diff --git a/model/registry/android.yaml b/model/registry/android.yaml index cfdcac8a46..c9c23e46ae 100644 --- a/model/registry/android.yaml +++ b/model/registry/android.yaml @@ -2,6 +2,7 @@ groups: - id: registry.android prefix: android type: attribute_group + display_name: Android Attributes brief: > The Android platform on which the Android application is running. attributes: diff --git a/model/registry/aspnetcore.yaml b/model/registry/aspnetcore.yaml index 0c93fc1aee..c5e36497e1 100644 --- a/model/registry/aspnetcore.yaml +++ b/model/registry/aspnetcore.yaml @@ -2,6 +2,7 @@ groups: - id: registry.aspnetcore prefix: aspnetcore type: attribute_group + display_name: ASP.NET Core Attributes brief: ASP.NET Core attributes attributes: - id: rate_limiting.policy diff --git a/model/registry/aws.yaml b/model/registry/aws.yaml index 90bb10b853..4ed5f82ff8 100644 --- a/model/registry/aws.yaml +++ b/model/registry/aws.yaml @@ -2,6 +2,7 @@ groups: - id: registry.aws prefix: aws type: attribute_group + display_name: General AWS Attributes brief: > This document defines generic attributes for AWS services. attributes: @@ -15,6 +16,7 @@ groups: - id: registry.aws.dynamodb prefix: aws.dynamodb type: attribute_group + display_name: Amazon DynamoDB Attributes brief: > This document defines attributes for AWS DynamoDB. attributes: @@ -256,6 +258,7 @@ groups: - id: registry.aws.ecs prefix: aws.ecs type: attribute_group + display_name: Amazon ECS Attributes brief: > This document defines attributes for AWS Elastic Container Service (ECS). attributes: @@ -316,6 +319,7 @@ groups: - id: registry.aws.eks prefix: aws.eks type: attribute_group + display_name: Amazon EKS Attributes brief: > This document defines attributes for AWS Elastic Kubernetes Service (EKS). attributes: @@ -328,6 +332,7 @@ groups: - id: registry.aws.log prefix: aws.log type: attribute_group + display_name: Amazon Logs Attributes brief: > This document defines attributes for AWS Logs. attributes: @@ -371,6 +376,7 @@ groups: - id: registry.aws.lambda prefix: aws.lambda type: attribute_group + display_name: Amazon Lambda Attributes brief: > This document defines attributes for AWS Lambda. attributes: @@ -385,6 +391,7 @@ groups: - id: registry.aws.s3 prefix: aws.s3 type: attribute_group + display_name: Amazon S3 Attributes brief: > This document defines attributes for AWS S3. attributes: diff --git a/model/registry/browser.yaml b/model/registry/browser.yaml index fad84c9787..4e6f39c3e3 100644 --- a/model/registry/browser.yaml +++ b/model/registry/browser.yaml @@ -2,6 +2,7 @@ groups: - id: registry.browser prefix: browser type: attribute_group + display_name: Browser Attributes brief: > The web browser attributes attributes: diff --git a/model/registry/client.yaml b/model/registry/client.yaml index 3b17ed8b4e..507dfd53a7 100644 --- a/model/registry/client.yaml +++ b/model/registry/client.yaml @@ -2,6 +2,7 @@ groups: - id: registry.client prefix: client type: attribute_group + display_name: Client Attributes brief: > These attributes may be used to describe the client in a connection-based network interaction where there is one side that initiates the connection (the client is the side that initiates the connection). diff --git a/model/registry/cloud.yaml b/model/registry/cloud.yaml index ddb83338cc..c86357be9d 100644 --- a/model/registry/cloud.yaml +++ b/model/registry/cloud.yaml @@ -2,6 +2,7 @@ groups: - id: registry.cloud prefix: cloud type: attribute_group + display_name: Cloud Attributes brief: > A cloud environment (e.g. GCP, Azure, AWS). attributes: diff --git a/model/registry/cloudevents.yaml b/model/registry/cloudevents.yaml index 4da702f8a8..61952f29b2 100644 --- a/model/registry/cloudevents.yaml +++ b/model/registry/cloudevents.yaml @@ -2,6 +2,7 @@ groups: - id: registry.cloudevents prefix: cloudevents type: attribute_group + display_name: CloudEvents Attributes brief: > This document defines attributes for CloudEvents. attributes: diff --git a/model/registry/code.yaml b/model/registry/code.yaml index 967607205a..b7119d5150 100644 --- a/model/registry/code.yaml +++ b/model/registry/code.yaml @@ -2,6 +2,7 @@ groups: - id: registry.code prefix: code type: attribute_group + display_name: Code Attributes brief: > These attributes allow to report this unit of code and therefore to provide more context about the span. attributes: diff --git a/model/registry/container.yaml b/model/registry/container.yaml index 60348628b4..750d8854bd 100644 --- a/model/registry/container.yaml +++ b/model/registry/container.yaml @@ -2,6 +2,7 @@ groups: - id: registry.container prefix: container type: attribute_group + display_name: Container Attributes brief: > A container instance. attributes: diff --git a/model/registry/cpu.yaml b/model/registry/cpu.yaml index 43fb145a38..93a327f9fa 100644 --- a/model/registry/cpu.yaml +++ b/model/registry/cpu.yaml @@ -3,6 +3,7 @@ groups: prefix: cpu type: attribute_group brief: Attributes specific to a cpu instance. + display_name: CPU Attributes attributes: - id: mode brief: "The mode of the CPU" diff --git a/model/registry/db.yaml b/model/registry/db.yaml index c94ac32e0f..8529414fbe 100644 --- a/model/registry/db.yaml +++ b/model/registry/db.yaml @@ -2,6 +2,7 @@ groups: - id: registry.db prefix: db type: attribute_group + display_name: General Database Attributes brief: > This group defines the attributes used to describe telemetry in the context of databases. attributes: @@ -340,6 +341,7 @@ groups: - id: registry.db.cassandra prefix: db type: attribute_group + display_name: Cassandra Attributes brief: > This group defines attributes for Cassandra. attributes: @@ -414,6 +416,7 @@ groups: - id: registry.db.cosmosdb prefix: db type: attribute_group + display_name: Azure Cosmos DB Attributes brief: > This group defines attributes for Azure Cosmos DB. attributes: @@ -509,6 +512,7 @@ groups: - id: registry.db.elasticsearch prefix: db type: attribute_group + display_name: Elasticsearch Attributes brief: > This group defines attributes for Elasticsearch. attributes: diff --git a/model/registry/deployment.yaml b/model/registry/deployment.yaml index ffc0050eab..0d4b6699bb 100644 --- a/model/registry/deployment.yaml +++ b/model/registry/deployment.yaml @@ -2,6 +2,7 @@ groups: - id: registry.deployment prefix: deployment type: attribute_group + display_name: Deployment Attributes brief: > This document defines attributes for software deployments. attributes: diff --git a/model/registry/deprecated/android.yaml b/model/registry/deprecated/android.yaml index 97e9bd1e7a..9445a91d5c 100644 --- a/model/registry/deprecated/android.yaml +++ b/model/registry/deprecated/android.yaml @@ -2,6 +2,7 @@ groups: - id: registry.android.deprecated prefix: android type: attribute_group + display_name: Deprecated Android Attributes brief: > This document defines attributes that represents an occurrence of a lifecycle transition on the Android platform. attributes: diff --git a/model/registry/deprecated/container.yaml b/model/registry/deprecated/container.yaml index 63e69621dd..01312d6865 100644 --- a/model/registry/deprecated/container.yaml +++ b/model/registry/deprecated/container.yaml @@ -1,6 +1,7 @@ groups: - id: registry.container.deprecated type: attribute_group + display_name: Deprecated Container Attributes brief: "Describes deprecated container attributes." attributes: - id: container.labels diff --git a/model/registry/deprecated/db.yaml b/model/registry/deprecated/db.yaml index a58a742881..4bdf5f1de3 100644 --- a/model/registry/deprecated/db.yaml +++ b/model/registry/deprecated/db.yaml @@ -2,6 +2,7 @@ groups: - id: registry.db.deprecated prefix: db type: attribute_group + display_name: Deprecated Database Attributes brief: > "Describes deprecated db attributes." attributes: @@ -94,6 +95,7 @@ groups: - id: registry.db.metrics.deprecated type: attribute_group + display_name: Deprecated Database Metrics brief: > "Describes deprecated db metrics attributes." attributes: diff --git a/model/registry/deprecated/enduser.yaml b/model/registry/deprecated/enduser.yaml index 8908ec8fbd..54e97dcde6 100644 --- a/model/registry/deprecated/enduser.yaml +++ b/model/registry/deprecated/enduser.yaml @@ -2,6 +2,7 @@ groups: - id: registry.enduser.deprecated prefix: enduser type: attribute_group + display_name: Deprecated End User Attributes brief: Describes deprecated enduser attributes. Complete enduser namespace has been deprecated attributes: - id: id diff --git a/model/registry/deprecated/gen-ai.yaml b/model/registry/deprecated/gen-ai.yaml index ca6abd6732..04a2968a74 100644 --- a/model/registry/deprecated/gen-ai.yaml +++ b/model/registry/deprecated/gen-ai.yaml @@ -2,6 +2,7 @@ groups: - id: registry.gen_ai.deprecated type: attribute_group brief: Describes deprecated `gen_ai` attributes. + display_name: Deprecated GenAI Attributes attributes: - id: gen_ai.usage.prompt_tokens type: int diff --git a/model/registry/deprecated/http.yaml b/model/registry/deprecated/http.yaml index 6fc36ef838..1c35ecdc5e 100644 --- a/model/registry/deprecated/http.yaml +++ b/model/registry/deprecated/http.yaml @@ -1,6 +1,7 @@ groups: - id: registry.http.deprecated type: attribute_group + display_name: Deprecated HTTP Attributes brief: "Describes deprecated HTTP attributes." prefix: http attributes: diff --git a/model/registry/deprecated/ios.yaml b/model/registry/deprecated/ios.yaml index acc1a9f1f9..326a40fcfd 100644 --- a/model/registry/deprecated/ios.yaml +++ b/model/registry/deprecated/ios.yaml @@ -2,6 +2,7 @@ groups: - id: registry.ios.deprecated prefix: ios type: attribute_group + display_name: Deprecated iOS Attributes brief: > The iOS platform on which the iOS application is running. attributes: diff --git a/model/registry/deprecated/k8s.yaml b/model/registry/deprecated/k8s.yaml index e2785dd08e..a928d2d31e 100644 --- a/model/registry/deprecated/k8s.yaml +++ b/model/registry/deprecated/k8s.yaml @@ -1,6 +1,7 @@ groups: - id: registry.k8s.deprecated type: attribute_group + display_name: Deprecated Kubernetes Attributes brief: "Describes deprecated k8s attributes." attributes: - id: k8s.pod.labels diff --git a/model/registry/deprecated/messaging.yaml b/model/registry/deprecated/messaging.yaml index 5f477018ad..c7dd7b05e5 100644 --- a/model/registry/deprecated/messaging.yaml +++ b/model/registry/deprecated/messaging.yaml @@ -1,6 +1,7 @@ groups: - id: registry.messaging.deprecated type: attribute_group + display_name: Deprecated Messaging Attributes brief: "Describes deprecated messaging attributes." attributes: - id: messaging.kafka.destination.partition diff --git a/model/registry/deprecated/network.yaml b/model/registry/deprecated/network.yaml index f13c79f9a9..7487f69adf 100644 --- a/model/registry/deprecated/network.yaml +++ b/model/registry/deprecated/network.yaml @@ -2,6 +2,7 @@ groups: - id: registry.network.deprecated prefix: net type: attribute_group + display_name: Deprecated Network Attributes brief: > These attributes may be used for any network related operation. attributes: diff --git a/model/registry/deprecated/otel.yaml b/model/registry/deprecated/otel.yaml index c52a51fe8c..b0b9cf0a8b 100644 --- a/model/registry/deprecated/otel.yaml +++ b/model/registry/deprecated/otel.yaml @@ -2,6 +2,7 @@ groups: - id: registry.otel.library.deprecated prefix: otel.library type: attribute_group + display_name: Deprecated OTel Library Attributes brief: "Describes deprecated otel.library attributes." attributes: - id: name diff --git a/model/registry/deprecated/process.yaml b/model/registry/deprecated/process.yaml index 33c5adb0cb..1c79cf81b2 100644 --- a/model/registry/deprecated/process.yaml +++ b/model/registry/deprecated/process.yaml @@ -2,6 +2,7 @@ groups: - id: registry.process.deprecated type: attribute_group brief: "Deprecated process attributes." + display_name: Deprecated Process Attributes attributes: - id: process.cpu.state brief: "Deprecated, use `cpu.mode` instead." diff --git a/model/registry/deprecated/rpc.yaml b/model/registry/deprecated/rpc.yaml index 1d9d22c2d4..e4b37f5d2b 100644 --- a/model/registry/deprecated/rpc.yaml +++ b/model/registry/deprecated/rpc.yaml @@ -1,6 +1,7 @@ groups: - id: registry.rpc.deprecated type: attribute_group + display_name: Deprecated RPC Attributes brief: 'Deprecated rpc message attributes.' attributes: - id: message.type diff --git a/model/registry/deprecated/system.yaml b/model/registry/deprecated/system.yaml index d220a501b7..8f2ece9d84 100644 --- a/model/registry/deprecated/system.yaml +++ b/model/registry/deprecated/system.yaml @@ -1,6 +1,7 @@ groups: - id: registry.system.deprecated type: attribute_group + display_name: Deprecated System Attributes brief: "Deprecated system attributes." attributes: - id: system.processes.status diff --git a/model/registry/destination.yaml b/model/registry/destination.yaml index c05a0c992a..a0631c5201 100644 --- a/model/registry/destination.yaml +++ b/model/registry/destination.yaml @@ -2,6 +2,7 @@ groups: - id: registry.destination prefix: destination type: attribute_group + display_name: Destination Attributes brief: > These attributes may be used to describe the receiver of a network exchange/packet. These should be used when there is no client/server relationship between the two sides, or when that relationship is unknown. diff --git a/model/registry/device.yaml b/model/registry/device.yaml index 5c324e37fe..901bf1869c 100644 --- a/model/registry/device.yaml +++ b/model/registry/device.yaml @@ -2,6 +2,7 @@ groups: - id: registry.device prefix: device type: attribute_group + display_name: Device Attributes brief: > Describes device attributes. attributes: diff --git a/model/registry/disk.yaml b/model/registry/disk.yaml index aa8c091135..b8dc420351 100644 --- a/model/registry/disk.yaml +++ b/model/registry/disk.yaml @@ -2,6 +2,7 @@ groups: - id: registry.disk prefix: disk type: attribute_group + display_name: Disk Attributes brief: > These attributes may be used for any disk related operation. attributes: diff --git a/model/registry/dns.yaml b/model/registry/dns.yaml index d4042c4add..f58187e0c9 100644 --- a/model/registry/dns.yaml +++ b/model/registry/dns.yaml @@ -1,6 +1,7 @@ groups: - id: registry.dns type: attribute_group + display_name: DNS Attributes prefix: dns brief: > This document defines the shared attributes used to report a DNS query. diff --git a/model/registry/error.yaml b/model/registry/error.yaml index 68bde170ba..95183df639 100644 --- a/model/registry/error.yaml +++ b/model/registry/error.yaml @@ -1,6 +1,7 @@ groups: - id: registry.error type: attribute_group + display_name: Error Attributes prefix: error brief: > This document defines the shared attributes used to report an error. diff --git a/model/registry/event.yaml b/model/registry/event.yaml index 5c246bfdff..0c1e32400e 100644 --- a/model/registry/event.yaml +++ b/model/registry/event.yaml @@ -2,6 +2,7 @@ groups: - id: registry.event prefix: event type: attribute_group + display_name: Event Attributes brief: > Attributes for Events represented using Log Records. attributes: diff --git a/model/registry/exception.yaml b/model/registry/exception.yaml index 70dea3d509..def10422b2 100644 --- a/model/registry/exception.yaml +++ b/model/registry/exception.yaml @@ -1,6 +1,7 @@ groups: - id: registry.exception type: attribute_group + display_name: Exception Attributes prefix: exception brief: > This document defines the shared attributes used to diff --git a/model/registry/faas.yaml b/model/registry/faas.yaml index a4fc8a3d55..6fb139fbf0 100644 --- a/model/registry/faas.yaml +++ b/model/registry/faas.yaml @@ -2,6 +2,7 @@ groups: - id: registry.faas brief: FaaS attributes type: attribute_group + display_name: Function as a Service Attributes prefix: faas attributes: - id: name diff --git a/model/registry/feature-flag.yaml b/model/registry/feature-flag.yaml index 9de106ffc8..1b41ff3898 100644 --- a/model/registry/feature-flag.yaml +++ b/model/registry/feature-flag.yaml @@ -2,6 +2,7 @@ groups: - id: registry.feature_flag prefix: feature_flag type: attribute_group + display_name: Feature Flag Attributes brief: > This document defines attributes for Feature Flags. attributes: diff --git a/model/registry/file.yaml b/model/registry/file.yaml index bbe0f99fd2..57d33a4106 100644 --- a/model/registry/file.yaml +++ b/model/registry/file.yaml @@ -2,6 +2,7 @@ groups: - id: registry.file prefix: file type: attribute_group + display_name: File Attributes brief: "Describes file attributes." attributes: - id: directory diff --git a/model/registry/gcp.yaml b/model/registry/gcp.yaml index 307713df87..66f9273d20 100644 --- a/model/registry/gcp.yaml +++ b/model/registry/gcp.yaml @@ -2,10 +2,12 @@ groups: - id: registry.gcp prefix: gcp type: attribute_group + display_name: GCP Attributes brief: Attributes for Google Cloud - id: registry.gcp.client prefix: gcp.client type: attribute_group + display_name: GCP Client Attributes brief: > Attributes for Google Cloud client libraries. attributes: @@ -22,6 +24,7 @@ groups: - id: registry.gcp.cloud_run prefix: gcp.cloud_run type: attribute_group + display_name: GCP - Google Cloud Run Attributes brief: > This document defines attributes for Google Cloud Run. attributes: @@ -46,6 +49,7 @@ groups: - id: registry.gcp.gce prefix: gcp.gce type: attribute_group + display_name: GCP - Google Compute Engine (GCE) Attributes brief: > This document defines attributes for Google Compute Engine (GCE). attributes: diff --git a/model/registry/gen-ai.yaml b/model/registry/gen-ai.yaml index ce6755a1db..820906f108 100644 --- a/model/registry/gen-ai.yaml +++ b/model/registry/gen-ai.yaml @@ -2,6 +2,7 @@ groups: - id: registry.gen_ai prefix: gen_ai type: attribute_group + display_name: GenAI Attributes brief: > This document defines the attributes used to describe telemetry in the context of Generative Artificial Intelligence (GenAI) Models requests and responses. attributes: diff --git a/model/registry/go.yaml b/model/registry/go.yaml index d599102301..2c3727d5c7 100644 --- a/model/registry/go.yaml +++ b/model/registry/go.yaml @@ -1,6 +1,7 @@ groups: - id: registry.go type: attribute_group + display_name: Go Attributes prefix: go brief: > This document defines Go related attributes. diff --git a/model/registry/graphql.yaml b/model/registry/graphql.yaml index 460444d891..ca015d017f 100644 --- a/model/registry/graphql.yaml +++ b/model/registry/graphql.yaml @@ -2,6 +2,7 @@ groups: - id: registry.graphql prefix: graphql type: attribute_group + display_name: GraphQL Attributes brief: 'This document defines attributes for GraphQL.' attributes: - id: operation.name diff --git a/model/registry/heroku.yaml b/model/registry/heroku.yaml index d9fe99a731..f9ff7a85e2 100644 --- a/model/registry/heroku.yaml +++ b/model/registry/heroku.yaml @@ -2,6 +2,7 @@ groups: - id: registry.heroku prefix: heroku type: attribute_group + display_name: Heroku Attributes brief: > This document defines attributes for the Android platform on which the Android application is running. attributes: diff --git a/model/registry/host.yaml b/model/registry/host.yaml index 332ea01f9c..fd2d3db9e1 100644 --- a/model/registry/host.yaml +++ b/model/registry/host.yaml @@ -2,6 +2,7 @@ groups: - id: registry.host prefix: host type: attribute_group + display_name: Host Attributes brief: > A host is defined as a computing instance. For example, physical servers, virtual machines, switches or disk array. attributes: diff --git a/model/registry/http.yaml b/model/registry/http.yaml index e013704a49..71583d4767 100644 --- a/model/registry/http.yaml +++ b/model/registry/http.yaml @@ -2,6 +2,7 @@ groups: - id: registry.http prefix: http type: attribute_group + display_name: HTTP Attributes brief: 'This document defines semantic convention attributes in the HTTP namespace.' attributes: - id: request.body.size diff --git a/model/registry/jvm.yaml b/model/registry/jvm.yaml index 5f3b14f7ec..9ec093f5fe 100644 --- a/model/registry/jvm.yaml +++ b/model/registry/jvm.yaml @@ -1,6 +1,7 @@ groups: - id: registry.jvm type: attribute_group + display_name: Java Virtual Machine (JVM) Attributes prefix: jvm brief: > This document defines Java Virtual machine related attributes. diff --git a/model/registry/k8s.yaml b/model/registry/k8s.yaml index 8b7de837f2..50f38b3132 100644 --- a/model/registry/k8s.yaml +++ b/model/registry/k8s.yaml @@ -2,6 +2,7 @@ groups: - id: registry.k8s prefix: k8s type: attribute_group + display_name: Kubernetes Attributes brief: > Kubernetes resource attributes. attributes: diff --git a/model/registry/log.yaml b/model/registry/log.yaml index bc18100451..399ec35b6b 100644 --- a/model/registry/log.yaml +++ b/model/registry/log.yaml @@ -1,6 +1,7 @@ groups: - id: registry.log type: attribute_group + display_name: General Log Attributes prefix: log brief: > This document defines log attributes @@ -23,6 +24,7 @@ groups: - id: registry.log.file # TODO: should we move it to the file model? type: attribute_group + display_name: Log File Attributes prefix: log.file brief: > Attributes for a file to which log was emitted. @@ -54,6 +56,7 @@ groups: - id: registry.log.record type: attribute_group + display_name: Log Record Attributes prefix: log.record brief: > This document defines the generic attributes that may be used in any Log Record. diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index 5c95891653..1c9fe27be2 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -2,6 +2,7 @@ groups: - id: registry.messaging prefix: messaging type: attribute_group + display_name: General Messaging Attributes brief: 'Attributes describing telemetry around messaging systems and messaging activities.' attributes: - id: batch.message_count @@ -217,6 +218,7 @@ groups: - id: registry.messaging.kafka prefix: messaging type: attribute_group + display_name: Kafka Attributes brief: > This group describes attributes specific to Apache Kafka. attributes: @@ -244,6 +246,7 @@ groups: - id: registry.messaging.rabbitmq prefix: messaging type: attribute_group + display_name: RabbitMQ Attributes brief: > This group describes attributes specific to RabbitMQ. attributes: @@ -262,6 +265,7 @@ groups: - id: registry.messaging.rocketmq prefix: messaging type: attribute_group + display_name: RocketMQ Attributes brief: > This group describes attributes specific to RocketMQ. attributes: @@ -342,6 +346,7 @@ groups: - id: registry.messaging.gcp_pubsub prefix: messaging type: attribute_group + display_name: GCP Pub/Sub Attributes brief: > This group describes attributes specific to GCP Pub/Sub. attributes: @@ -372,6 +377,7 @@ groups: - id: registry.messaging.servicebus prefix: messaging type: attribute_group + display_name: Azure Service Bus Attributes brief: > This group describes attributes specific to Azure Service Bus. attributes: @@ -413,6 +419,7 @@ groups: - id: registry.messaging.eventhubs prefix: messaging type: attribute_group + display_name: Azure Event Hubs Attributes brief: > This group describes attributes specific to Azure Event Hubs. attributes: diff --git a/model/registry/network.yaml b/model/registry/network.yaml index 2f3f19576c..322c0ddc8c 100644 --- a/model/registry/network.yaml +++ b/model/registry/network.yaml @@ -2,6 +2,7 @@ groups: - id: registry.network prefix: network type: attribute_group + display_name: Network Attributes brief: > These attributes may be used for any network related operation. attributes: diff --git a/model/registry/oci.yaml b/model/registry/oci.yaml index 00d0e28c2b..da0ce6dace 100644 --- a/model/registry/oci.yaml +++ b/model/registry/oci.yaml @@ -2,6 +2,7 @@ groups: - id: registry.oci.manifest prefix: oci.manifest type: attribute_group + display_name: Open Container Initiative (OCI) Attributes brief: > An OCI image manifest. attributes: diff --git a/model/registry/opentracing.yaml b/model/registry/opentracing.yaml index fd9d68e380..c5cafc291e 100644 --- a/model/registry/opentracing.yaml +++ b/model/registry/opentracing.yaml @@ -2,6 +2,7 @@ groups: - id: registry.opentracing prefix: opentracing type: attribute_group + display_name: OpenTracing Attributes brief: Attributes used by the OpenTracing Shim layer. attributes: - id: ref_type diff --git a/model/registry/os.yaml b/model/registry/os.yaml index 3317958f16..18b59568a0 100644 --- a/model/registry/os.yaml +++ b/model/registry/os.yaml @@ -2,6 +2,7 @@ groups: - id: registry.os prefix: os type: attribute_group + display_name: Operating System Attributes brief: > The operating system (OS) on which the process represented by this resource is running. note: > diff --git a/model/registry/otel.yaml b/model/registry/otel.yaml index 76286cdc9b..8ed9405a58 100644 --- a/model/registry/otel.yaml +++ b/model/registry/otel.yaml @@ -2,6 +2,7 @@ groups: - id: registry.otel prefix: otel type: attribute_group + display_name: OTel Attributes brief: Attributes reserved for OpenTelemetry attributes: - id: status_code @@ -26,6 +27,7 @@ groups: - id: registry.otel.scope prefix: otel.scope type: attribute_group + display_name: OTel Scope Attributes brief: Attributes used by non-OTLP exporters to represent OpenTelemetry Scope's concepts. attributes: - id: name diff --git a/model/registry/peer.yaml b/model/registry/peer.yaml index a6e38a129d..ee9d3f722f 100644 --- a/model/registry/peer.yaml +++ b/model/registry/peer.yaml @@ -1,6 +1,7 @@ groups: - id: registry.peer type: attribute_group + display_name: Peer Attributes prefix: peer brief: > Operations that access some remote service. diff --git a/model/registry/process.yaml b/model/registry/process.yaml index d9c0575ae7..bc8362357d 100644 --- a/model/registry/process.yaml +++ b/model/registry/process.yaml @@ -2,6 +2,7 @@ groups: - id: registry.process prefix: process type: attribute_group + display_name: Process Attributes brief: > An operating system process. attributes: diff --git a/model/registry/rpc.yaml b/model/registry/rpc.yaml index d1e0aa05cf..8e04df3224 100644 --- a/model/registry/rpc.yaml +++ b/model/registry/rpc.yaml @@ -2,6 +2,7 @@ groups: - id: registry.rpc prefix: rpc type: attribute_group + display_name: Remote Procedure Call (RPC) Attributes brief: 'This document defines attributes for remote procedure calls.' attributes: - id: connect_rpc.error_code diff --git a/model/registry/server.yaml b/model/registry/server.yaml index d6927fe98a..9da2b85ae1 100644 --- a/model/registry/server.yaml +++ b/model/registry/server.yaml @@ -2,6 +2,7 @@ groups: - id: registry.server prefix: server type: attribute_group + display_name: Server Attributes brief: > These attributes may be used to describe the server in a connection-based network interaction where there is one side that initiates the connection (the client is the side that initiates the connection). diff --git a/model/registry/service.yaml b/model/registry/service.yaml index 5af22be57e..44bc2985f6 100644 --- a/model/registry/service.yaml +++ b/model/registry/service.yaml @@ -2,6 +2,7 @@ groups: - id: registry.service prefix: service type: attribute_group + display_name: Service Attributes brief: > A service instance. attributes: diff --git a/model/registry/session.yaml b/model/registry/session.yaml index 3f53c9c6cd..bf39e6ca30 100644 --- a/model/registry/session.yaml +++ b/model/registry/session.yaml @@ -2,6 +2,7 @@ groups: - id: registry.session prefix: session type: attribute_group + display_name: Session Attributes brief: > Session is defined as the period of time encompassing all activities performed by the application and the actions executed by the end user. diff --git a/model/registry/signalr.yaml b/model/registry/signalr.yaml index 879034e7b3..4e87161712 100644 --- a/model/registry/signalr.yaml +++ b/model/registry/signalr.yaml @@ -2,6 +2,7 @@ groups: - id: registry.signalr prefix: signalr type: attribute_group + display_name: SignalR Attributes brief: SignalR attributes attributes: - id: connection.status diff --git a/model/registry/source.yaml b/model/registry/source.yaml index 077da82310..9e0a8af449 100644 --- a/model/registry/source.yaml +++ b/model/registry/source.yaml @@ -2,6 +2,7 @@ groups: - id: registry.source prefix: source type: attribute_group + display_name: Source Attributes brief: > These attributes may be used to describe the sender of a network exchange/packet. These should be used when there is no client/server relationship between the two sides, or when that relationship is unknown. diff --git a/model/registry/system.yaml b/model/registry/system.yaml index 790a1374af..c7d8cbc0d8 100644 --- a/model/registry/system.yaml +++ b/model/registry/system.yaml @@ -3,6 +3,7 @@ groups: - id: registry.system prefix: system type: attribute_group + display_name: General System Attributes brief: "Describes System attributes" attributes: - id: device @@ -14,6 +15,7 @@ groups: - id: registry.system.cpu prefix: system.cpu type: attribute_group + display_name: System CPU Attributes brief: "Describes System CPU attributes" attributes: - id: logical_number @@ -25,6 +27,7 @@ groups: - id: registry.system.memory prefix: system.memory type: attribute_group + display_name: System Memory Attributes brief: "Describes System Memory attributes" attributes: - id: state @@ -54,6 +57,7 @@ groups: - id: registry.system.paging prefix: system.paging type: attribute_group + display_name: System Paging Attributes brief: "Describes System Memory Paging attributes" attributes: - id: state @@ -98,6 +102,7 @@ groups: - id: registry.system.filesystem prefix: system.filesystem type: attribute_group + display_name: Filesystem Attributes brief: "Describes Filesystem attributes" attributes: - id: state @@ -155,6 +160,7 @@ groups: - id: registry.system.network prefix: system.network type: attribute_group + display_name: System Network Attributes brief: "Describes Network attributes" attributes: - id: state @@ -204,6 +210,7 @@ groups: - id: registry.system.process prefix: system.process type: attribute_group + display_name: System Process Attributes brief: "Describes System Process attributes" attributes: - id: status diff --git a/model/registry/telemetry.yaml b/model/registry/telemetry.yaml index 2179330323..97b762377a 100644 --- a/model/registry/telemetry.yaml +++ b/model/registry/telemetry.yaml @@ -2,6 +2,7 @@ groups: - id: registry.telemetry prefix: telemetry type: attribute_group + display_name: Telemetry Attributes brief: > This document defines attributes for telemetry SDK. attributes: diff --git a/model/registry/thread.yaml b/model/registry/thread.yaml index 9c99772b9b..b6f3556107 100644 --- a/model/registry/thread.yaml +++ b/model/registry/thread.yaml @@ -2,6 +2,7 @@ groups: - id: registry.thread prefix: thread type: attribute_group + display_name: Thread Attributes brief: > These attributes may be used for any operation to store information about a thread that started a span. attributes: diff --git a/model/registry/tls.yaml b/model/registry/tls.yaml index 2c4f31a752..f4937dfb78 100644 --- a/model/registry/tls.yaml +++ b/model/registry/tls.yaml @@ -2,6 +2,7 @@ groups: - id: registry.tls prefix: tls type: attribute_group + display_name: TLS Attributes brief: "This document defines semantic convention attributes in the TLS namespace." attributes: - id: cipher diff --git a/model/registry/url.yaml b/model/registry/url.yaml index f979c23a5f..0c808ad5f0 100644 --- a/model/registry/url.yaml +++ b/model/registry/url.yaml @@ -2,6 +2,7 @@ groups: - id: registry.url brief: Attributes describing URL. type: attribute_group + display_name: URL Attributes prefix: url attributes: - id: domain diff --git a/model/registry/user-agent.yaml b/model/registry/user-agent.yaml index 5503454d22..9520c8c5d8 100644 --- a/model/registry/user-agent.yaml +++ b/model/registry/user-agent.yaml @@ -2,6 +2,7 @@ groups: - id: registry.user_agent prefix: user_agent type: attribute_group + display_name: User-agent Attributes brief: "Describes user-agent attributes." attributes: - id: original diff --git a/model/registry/user.yaml b/model/registry/user.yaml index 98792de275..10178f00a8 100644 --- a/model/registry/user.yaml +++ b/model/registry/user.yaml @@ -2,6 +2,7 @@ groups: - id: registry.user prefix: user type: attribute_group + display_name: User Attributes brief: "Describes information about the user." attributes: - id: email diff --git a/model/registry/v8js.yaml b/model/registry/v8js.yaml index a03cbe7143..d39f6e0967 100644 --- a/model/registry/v8js.yaml +++ b/model/registry/v8js.yaml @@ -2,6 +2,7 @@ groups: - id: registry.v8js type: attribute_group brief: Describes V8 JS Engine Runtime related attributes. + display_name: V8 JS Attributes prefix: v8js attributes: - id: gc.type diff --git a/model/registry/webengine.yaml b/model/registry/webengine.yaml index a1579b7d24..97d01e45aa 100644 --- a/model/registry/webengine.yaml +++ b/model/registry/webengine.yaml @@ -2,6 +2,7 @@ groups: - id: registry.webengine prefix: webengine type: attribute_group + display_name: Web Engine Attributes brief: > This document defines the attributes used to describe the packaged software running the application code. attributes: diff --git a/templates/registry/markdown/attribute_macros.j2 b/templates/registry/markdown/attribute_macros.j2 index de9321eae6..7ac1d474c0 100644 --- a/templates/registry/markdown/attribute_macros.j2 +++ b/templates/registry/markdown/attribute_macros.j2 @@ -34,3 +34,10 @@ {%- endif %}{%- elif attribute.type is mapping %} {%- for e in attribute.type.members %}{% if loop.index0 < 3 %}{% if loop.first == false %}; {% endif %}`{{ e.value | trim }}`{% endif %}{%- endfor %} {%- endif %}{% endmacro %} + +{% macro display_name(group) %} +{%- if 'display_name' in group %}{{ group.display_name }} +{%- else %}{{ group.id | split_id | list | reject("eq", "registry") | join(" ") | title_case | acronym }} Attributes +{%- endif %}{% endmacro %} + +{% macro heading_link_fragments(title) %}{{ title | trim | lower | replace(" ", "-") | replace("(", "") | replace(")", "") | replace("/", "") | replace("\\", "") | replace(".", "") | replace("!", "") | replace("?", "") | replace("~", "") | replace("#", "")}}{% endmacro %} diff --git a/templates/registry/markdown/attribute_namespace.md.j2 b/templates/registry/markdown/attribute_namespace.md.j2 index 432943393d..edf210f99d 100644 --- a/templates/registry/markdown/attribute_namespace.md.j2 +++ b/templates/registry/markdown/attribute_namespace.md.j2 @@ -9,6 +9,15 @@ {% import 'attribute_macros.j2' as attrs %} {%- set my_file_name = ctx.id | lower | kebab_case ~ ".md" -%} {{- template.set_file_name(my_file_name) -}} +{%- set groups = namespace(deprecated=[], non_deprecated=[]) -%} +{% for group in ctx.groups | sort(attribute="id") %} +{% if group.id[-10:] == "deprecated" %} +{%- set groups.deprecated = groups.deprecated + [group] -%} +{%- else -%} +{%- set groups.non_deprecated = groups.non_deprecated + [group] -%} +{%- endif -%} +{%- endfor -%} +{%- set attr_groups = groups.non_deprecated + groups.deprecated -%} @@ -18,12 +27,12 @@ # {{ ctx.id | title_case | acronym }} -{% if ctx.groups | length > 1 %}{% for group in ctx.groups | sort(attribute="id") %} -{%- set group_name = group.id | split_id | list | reject("eq", "registry") | join(" ") -%} -- [{{ group_name | title_case }}](#{{group_name | kebab_case }}-attributes) -{% endfor %}{% endif %} -{% for group in ctx.groups | sort(attribute="id") %} -## {{ group.id | split_id | list | reject("eq", "registry") | join(" ") | title_case | acronym }} Attributes +{%- if attr_groups | length > 1 %}{% for group in attr_groups %} +- [{{ attrs.display_name(group) }}](#{{ attrs.heading_link_fragments(attrs.display_name(group)) }}) +{%- endfor -%}{%- endif -%} + +{% for group in attr_groups %} +## {{ attrs.display_name(group) }} {{ group.brief }} From dde9dbd25edf30961df2fb26d47d065f2f0760d7 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 15 Jul 2024 07:57:17 -0700 Subject: [PATCH 18/23] Clarify that DB and messaging system-specific conventions override common ones (#1244) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/1244.yaml | 4 + docs/database/cassandra.md | 4 +- docs/database/cosmosdb.md | 4 +- docs/database/couchdb.md | 4 +- docs/database/dynamodb.md | 111 ++++-------------------- docs/database/elasticsearch.md | 4 +- docs/database/hbase.md | 4 +- docs/database/mongodb.md | 4 +- docs/database/mssql.md | 4 +- docs/database/redis.md | 4 +- docs/messaging/azure-messaging.md | 2 +- docs/messaging/gcp-pubsub.md | 2 +- docs/messaging/kafka.md | 4 +- docs/messaging/rabbitmq.md | 4 +- docs/messaging/rocketmq.md | 4 +- model/trace/instrumentation/aws-sdk.yml | 10 --- 16 files changed, 32 insertions(+), 141 deletions(-) create mode 100644 .chloggen/1244.yaml diff --git a/.chloggen/1244.yaml b/.chloggen/1244.yaml new file mode 100644 index 0000000000..849a02c9ff --- /dev/null +++ b/.chloggen/1244.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: db, messaging +note: Clarify that DB and messaging system-specific conventions override common ones +issues: [ 1235, 1244 ] diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index 3b8837df60..be65ba773e 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -6,9 +6,7 @@ linkTitle: Cassandra **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend and override the [Database Semantic Conventions](database-spans.md) -that describe common database operations attributes in addition to the Semantic Conventions -described on this page. +The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend and override the [Database Semantic Conventions](database-spans.md). `db.system` MUST be set to `"cassandra"` and SHOULD be provided **at span creation time**. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index b6f4330082..593d42fb42 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -7,9 +7,7 @@ linkTitle: Cosmos DB **Status**: [Experimental][DocumentStatus] The Semantic Conventions for [Microsoft Cosmos DB](https://azure.microsoft.com/products/cosmos-db/) -extend and override the [Database Semantic Conventions](database-spans.md) -that describe common database operations attributes in addition to the Semantic Conventions -described on this page. +extend and override the [Database Semantic Conventions](database-spans.md). ## Attributes diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index 7d33f249b4..f72458104b 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -6,9 +6,7 @@ linkTitle: CouchDB **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and override the [Database Semantic Conventions](database-spans.md) -that describe common database operations attributes in addition to the Semantic Conventions -described on this page. +The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and override the [Database Semantic Conventions](database-spans.md). `db.system` MUST be set to `"couchdb"` and SHOULD be provided **at span creation time**. diff --git a/docs/database/dynamodb.md b/docs/database/dynamodb.md index eb342339f0..bb83447e94 100644 --- a/docs/database/dynamodb.md +++ b/docs/database/dynamodb.md @@ -7,94 +7,13 @@ linkTitle: AWS DynamoDB **Status**: [Experimental][DocumentStatus] The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) extend and override the general -[AWS SDK Semantic Conventions](/docs/cloud-providers/aws-sdk.md) -that describe common AWS SDK attributes and the [Database Semantic Conventions](database-spans.md). -that describe common database operations attributes in addition to the Semantic Conventions -described on this page. +[AWS SDK Semantic Conventions](/docs/cloud-providers/aws-sdk.md) and [Database Semantic Conventions](database-spans.md). -## Common Attributes - -These attributes are filled in for all DynamoDB request types. - - - - - - - - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`db.system`](/docs/attributes-registry/db.md) | string | The value `dynamodb`. [1] | `dynamodb` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge. - - - -`db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -|---|---|---| -| `adabas` | Adabas (Adaptable Database System) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cassandra` | Apache Cassandra | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `clickhouse` | ClickHouse | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cockroachdb` | CockroachDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cosmosdb` | Microsoft Azure Cosmos DB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `couchbase` | Couchbase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `couchdb` | CouchDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db2` | IBM Db2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `derby` | Apache Derby | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `dynamodb` | Amazon DynamoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `edb` | EnterpriseDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `elasticsearch` | Elasticsearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `filemaker` | FileMaker | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `firebird` | Firebird | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `geode` | Apache Geode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `h2` | H2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `hanadb` | SAP HANA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `hbase` | Apache HBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `hive` | Apache Hive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `hsqldb` | HyperSQL DataBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `influxdb` | InfluxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `informix` | Informix | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `ingres` | Ingres | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `instantdb` | InstantDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `interbase` | InterBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `intersystems_cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mariadb` | MariaDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `maxdb` | SAP MaxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mssql` | Microsoft SQL Server | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mysql` | MySQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `netezza` | Netezza | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `opensearch` | OpenSearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `oracle` | Oracle Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `other_sql` | Some other SQL database. Fallback only. See notes. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `pervasive` | Pervasive PSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `pointbase` | PointBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `postgresql` | PostgreSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `progress` | Progress Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `redis` | Redis | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `redshift` | Amazon Redshift | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `spanner` | Cloud Spanner | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `sqlite` | SQLite | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `sybase` | Sybase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `teradata` | Teradata | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `trino` | Trino | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `vertica` | Vertica | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - - - - - - - +`db.system` MUST be set to `"dynamodb"` and SHOULD be provided **at span creation time**. ## DynamoDB.BatchGetItem - + @@ -135,7 +54,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.BatchWriteItem - + @@ -177,7 +96,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.CreateTable - + @@ -223,7 +142,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.DeleteItem - + @@ -265,7 +184,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.DeleteTable - + @@ -305,7 +224,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.DescribeTable - + @@ -345,7 +264,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.GetItem - + @@ -388,7 +307,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.ListTables - + @@ -430,7 +349,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.PutItem - + @@ -472,7 +391,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.Query - + @@ -520,7 +439,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.Scan - + @@ -571,7 +490,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.UpdateItem - + @@ -613,7 +532,7 @@ These attributes are filled in for all DynamoDB request types. ## DynamoDB.UpdateTable - + diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 0c6fcb3c98..8ebadbaa4d 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -6,9 +6,7 @@ linkTitle: Elasticsearch **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [Elasticsearch](https://www.elastic.co/) extend and override the [Database Semantic Conventions](database-spans.md) -that describe common database operations attributes in addition to the Semantic Conventions -described on this page. +The Semantic Conventions for [Elasticsearch](https://www.elastic.co/) extend and override the [Database Semantic Conventions](database-spans.md). `db.system` MUST be set to `"elasticsearch"` and SHOULD be provided **at span creation time**. diff --git a/docs/database/hbase.md b/docs/database/hbase.md index 6e6419862b..1fc8c19d91 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -6,9 +6,7 @@ linkTitle: HBase **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [HBase](https://hbase.apache.org/) extend and override the [Database Semantic Conventions](database-spans.md) -that describe common database operations attributes in addition to the Semantic Conventions -described on this page. +The Semantic Conventions for [HBase](https://hbase.apache.org/) extend and override the [Database Semantic Conventions](database-spans.md). `db.system` MUST be set to `"hbase"` and SHOULD be provided **at span creation time**. diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index ff3f18891c..ff514fc0fe 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -6,9 +6,7 @@ linkTitle: MongoDB **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [MongoDB](https://www.mongodb.com/) extend and override the [Database Semantic Conventions](database-spans.md) -that describe common database operations attributes in addition to the Semantic Conventions -described on this page. +The Semantic Conventions for [MongoDB](https://www.mongodb.com/) extend and override the [Database Semantic Conventions](database-spans.md). `db.system` MUST be set to `"mongodb"` and SHOULD be provided **at span creation time**. diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 8ea95cbe8a..50460220d2 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -6,9 +6,7 @@ linkTitle: MSSQL **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for the *Microsoft SQL Server* extend and override the [Database Semantic Conventions](database-spans.md) -that describe common database operations attributes in addition to the Semantic Conventions -described on this page. +The Semantic Conventions for the *Microsoft SQL Server* extend and override the [Database Semantic Conventions](database-spans.md). `db.system` MUST be set to `"mssql"` and SHOULD be provided **at span creation time**. diff --git a/docs/database/redis.md b/docs/database/redis.md index 71ebcf9ee9..501a239ed5 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -6,9 +6,7 @@ linkTitle: Redis **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [Redis](https://redis.com/) extend and override the [Database Semantic Conventions](database-spans.md) -that describe common database operations attributes in addition to the Semantic Conventions -described on this page. +The Semantic Conventions for [Redis](https://redis.com/) extend and override the [Database Semantic Conventions](database-spans.md). `db.system` MUST be set to `"redis"` and SHOULD be provided **at span creation time**. diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md index 0d2d6e4e7d..72ef2814e2 100644 --- a/docs/messaging/azure-messaging.md +++ b/docs/messaging/azure-messaging.md @@ -6,7 +6,7 @@ linkTitle: Azure Messaging **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [Azure Service Bus](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-messaging-overview) and [Azure Event Hubs](https://learn.microsoft.com/azure/event-hubs/event-hubs-about) extend and override the [Messaging Semantic Conventions](README.md) that describe common messaging operations attributes in addition to the Semantic Conventions described on this page. +The Semantic Conventions for [Azure Service Bus](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-messaging-overview) and [Azure Event Hubs](https://learn.microsoft.com/azure/event-hubs/event-hubs-about) extend and override the [Messaging Semantic Conventions](README.md). ## Azure Service Bus diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md index 1957e3dbbc..c9286a02b6 100644 --- a/docs/messaging/gcp-pubsub.md +++ b/docs/messaging/gcp-pubsub.md @@ -6,7 +6,7 @@ linkTitle: Google Cloud Pub/Sub **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) extend and override the [Messaging Semantic Conventions](README.md) that describe common messaging operations attributes in addition to the Semantic Conventions described on this page. +The Semantic Conventions for [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) extend and override the [Messaging Semantic Conventions](README.md). `messaging.system` MUST be set to `"gcp_pubsub"` and SHOULD be provided **at span creation time**. diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index 14b01a072d..b2fd1b4dab 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -14,9 +14,7 @@ linkTitle: Kafka -The Semantic Conventions for [Apache Kafka](https://kafka.apache.org/) extend and override the [Messaging Semantic Conventions](README.md) -that describe common messaging operations attributes in addition to the Semantic Conventions -described on this page. +The Semantic Conventions for [Apache Kafka](https://kafka.apache.org/) extend and override the [Messaging Semantic Conventions](README.md). `messaging.system` MUST be set to `"kafka"` and SHOULD be provided **at span creation time**. diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md index bd4a1ed73d..3648280e3e 100644 --- a/docs/messaging/rabbitmq.md +++ b/docs/messaging/rabbitmq.md @@ -6,9 +6,7 @@ linkTitle: RabbitMQ **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [RabbitMQ](https://www.rabbitmq.com/) extend and override the [Messaging Semantic Conventions](README.md) -that describe common messaging operations attributes in addition to the Semantic Conventions -described on this page. +The Semantic Conventions for [RabbitMQ](https://www.rabbitmq.com/) extend and override the [Messaging Semantic Conventions](README.md). `messaging.system` MUST be set to `"rabbitmq"` and SHOULD be provided **at span creation time**. diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md index a602244433..6317f0cc3c 100644 --- a/docs/messaging/rocketmq.md +++ b/docs/messaging/rocketmq.md @@ -6,9 +6,7 @@ linkTitle: RocketMQ **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [Apache RocketMQ](https://rocketmq.apache.org/) extend and override the [Messaging Semantic Conventions](README.md) -that describe common messaging operations attributes in addition to the Semantic Conventions -described on this page. +The Semantic Conventions for [Apache RocketMQ](https://rocketmq.apache.org/) extend and override the [Messaging Semantic Conventions](README.md). `messaging.system` MUST be set to `"rocketmq"` and SHOULD be provided **at span creation time**. diff --git a/model/trace/instrumentation/aws-sdk.yml b/model/trace/instrumentation/aws-sdk.yml index aac648e688..a2ea68a4f8 100644 --- a/model/trace/instrumentation/aws-sdk.yml +++ b/model/trace/instrumentation/aws-sdk.yml @@ -29,16 +29,6 @@ groups: - ref: aws.request_id requirement_level: recommended - - id: dynamodb.all - type: span - brief: "Attributes always filled for all DynamoDB request types." - attributes: - - ref: db.system - brief: "The value `dynamodb`." - requirement_level: required - examples: - - dynamodb - - id: dynamodb.shared extends: aws type: span From 17decc3f2212680d6b98d8c2ce52db7febb31f11 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 15 Jul 2024 09:04:16 -0700 Subject: [PATCH 19/23] Add QUIC to the list of well known network transports (#1239) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/1239.yaml | 4 ++++ docs/attributes-registry/network.md | 13 +++++++------ docs/dotnet/dotnet-kestrel-metrics.md | 8 ++++++++ docs/general/attributes.md | 1 + docs/http/http-spans.md | 2 ++ docs/rpc/rpc-metrics.md | 1 + docs/rpc/rpc-spans.md | 2 ++ docs/system/system-metrics.md | 1 + model/registry/network.yaml | 4 ++++ 9 files changed, 30 insertions(+), 6 deletions(-) create mode 100644 .chloggen/1239.yaml diff --git a/.chloggen/1239.yaml b/.chloggen/1239.yaml new file mode 100644 index 0000000000..33a9ee75cb --- /dev/null +++ b/.chloggen/1239.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: network +note: Add QUIC to the list of well known network transports +issues: [ 1237, 1239 ] diff --git a/docs/attributes-registry/network.md b/docs/attributes-registry/network.md index 1d1e742e6b..15375fb86b 100644 --- a/docs/attributes-registry/network.md +++ b/docs/attributes-registry/network.md @@ -88,12 +88,13 @@ different processes could be listening on TCP port 12345 and UDP port 12345. `network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Value | Description | Stability | -| ------ | ------------------------ | ---------------------------------------------------------- | -| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| Value | Description | Stability | +| ------ | ------------------------ | ---------------------------------------------------------------- | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 98860c6a05..56d2696acb 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -86,6 +86,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -182,6 +183,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -258,6 +260,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -333,6 +336,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -414,6 +418,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -491,6 +496,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -581,6 +587,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -656,6 +663,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/general/attributes.md b/docs/general/attributes.md index f8da8d3a6c..895fbe8e4e 100644 --- a/docs/general/attributes.md +++ b/docs/general/attributes.md @@ -245,6 +245,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index a22e33506b..c931045c94 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -258,6 +258,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -522,6 +523,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index f8c83543e2..1642389989 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -386,6 +386,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 610d7c85d6..0595583160 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -138,6 +138,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -220,6 +221,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index cd01009e28..dbdee390f8 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -1305,6 +1305,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/model/registry/network.yaml b/model/registry/network.yaml index 322c0ddc8c..847a64c94d 100644 --- a/model/registry/network.yaml +++ b/model/registry/network.yaml @@ -195,6 +195,10 @@ groups: value: 'unix' brief: "Unix domain socket" stability: stable + - id: quic + value: 'quic' + brief: "QUIC" + stability: experimental brief: > [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). From c06b31850b43ad01c56b66177aa90cca0b9ff50f Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Mon, 15 Jul 2024 18:47:18 +0200 Subject: [PATCH 20/23] Rename `messaging.kafka.message.offset` to `messaging.kafka.offset` (#1245) Co-authored-by: Liudmila Molkova --- .chloggen/1156.yaml | 7 +++++++ docs/attributes-registry/messaging.md | 3 ++- docs/messaging/kafka.md | 2 +- model/registry/deprecated/messaging.yaml | 8 ++++++++ model/registry/messaging.yaml | 2 +- model/trace/messaging.yaml | 2 +- schema-next.yaml | 4 ++++ 7 files changed, 24 insertions(+), 4 deletions(-) create mode 100644 .chloggen/1156.yaml diff --git a/.chloggen/1156.yaml b/.chloggen/1156.yaml new file mode 100644 index 0000000000..56ef916b8e --- /dev/null +++ b/.chloggen/1156.yaml @@ -0,0 +1,7 @@ +change_type: breaking + +component: messaging + +note: Rename `messaging.kafka.message.offset` to `messaging.kafka.offset` + +issues: [1156] diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index cf7a11b0b1..e670a5e58f 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -117,8 +117,8 @@ This group describes attributes specific to Apache Kafka. | Attribute | Type | Description | Examples | Stability | | ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------- | | `messaging.kafka.message.key` | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [11] | `myKey` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.kafka.message.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.kafka.message.tombstone` | boolean | A boolean that is true if the message is a tombstone. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.kafka.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[11]:** If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value. @@ -191,6 +191,7 @@ Describes deprecated messaging attributes. | `messaging.eventhubs.consumer.group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `$Default` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name`. | | `messaging.kafka.consumer.group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `my-group` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name`. | | `messaging.kafka.destination.partition` | int | Deprecated, use `messaging.destination.partition.id` instead. | `2` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.destination.partition.id`. | +| `messaging.kafka.message.offset` | int | Deprecated, use `messaging.kafka.offset` instead. | `42` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.kafka.offset`. | | `messaging.operation` | string | Deprecated, use `messaging.operation.type` instead. | `publish`; `create`; `process` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.operation.type`. | | `messaging.rocketmq.client_group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `myConsumerGroup` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name` on the consumer spans. No replacement for producer spans. | | `messaging.servicebus.destination.subscription_name` | string | Deprecated, use `messaging.servicebus.destination.subscription_name` instead. | `subscription-a` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.servicebus.destination.subscription_name`. | diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index b2fd1b4dab..2964be5d02 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -42,7 +42,7 @@ For Apache Kafka, the following additional attributes are defined: | [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) | string | Kafka [consumer group id](https://docs.confluent.io/platform/current/clients/consumer.html). | `my-group`; `indexer` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | String representation of the partition id the message (or batch) is sent to or received from. | `1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.kafka.message.key`](/docs/attributes-registry/messaging.md) | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [9] | `myKey` | `Recommended` If span describes operation on a single message. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.kafka.message.offset`](/docs/attributes-registry/messaging.md) | int | The offset of a record in the corresponding Kafka partition. | `42` | `Recommended` If span describes operation on a single message. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.kafka.offset`](/docs/attributes-registry/messaging.md) | int | The offset of a record in the corresponding Kafka partition. | `42` | `Recommended` If span describes operation on a single message. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. [10] | `1439` | `Recommended` If span describes operation on a single message. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.id`](/docs/attributes-registry/messaging.md) | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | `Recommended` If span describes operation on a single message. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [11] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/model/registry/deprecated/messaging.yaml b/model/registry/deprecated/messaging.yaml index c7dd7b05e5..f7144862db 100644 --- a/model/registry/deprecated/messaging.yaml +++ b/model/registry/deprecated/messaging.yaml @@ -57,3 +57,11 @@ groups: examples: 'subscription-a' deprecated: > Replaced by `messaging.servicebus.destination.subscription_name`. + - id: messaging.kafka.message.offset + type: int + stability: experimental + brief: > + Deprecated, use `messaging.kafka.offset` instead. + examples: 42 + deprecated: > + Replaced by `messaging.kafka.offset`. diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index 1c9fe27be2..7a06243fc4 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -233,7 +233,7 @@ groups: If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value. examples: 'myKey' - - id: kafka.message.offset + - id: kafka.offset type: int stability: experimental brief: > diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index 52bf65c542..0d3c9f067d 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -151,7 +151,7 @@ groups: - ref: messaging.kafka.message.key requirement_level: recommended: If span describes operation on a single message. - - ref: messaging.kafka.message.offset + - ref: messaging.kafka.offset requirement_level: recommended: If span describes operation on a single message. - ref: messaging.kafka.message.tombstone diff --git a/schema-next.yaml b/schema-next.yaml index b2d310bd77..3539f102a7 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -4,6 +4,10 @@ versions: next: all: changes: + # https://github.com/open-telemetry/semantic-conventions/pull/1245 + - rename_attributes: + attribute_map: + messaging.kafka.message.offset: messaging.kafka.offset # https://github.com/open-telemetry/semantic-conventions/pull/815 - rename_attributes: attribute_map: From d7115c8aecbfaa6ed2f5d57def9761bca3364af2 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 15 Jul 2024 11:40:23 -0700 Subject: [PATCH 21/23] Deprecate `messaging.destination_publish.*` namespace and remove all usages (#1241) --- .chloggen/1241.yaml | 4 ++ docs/attributes-registry/messaging.md | 47 +++++++++++------------ docs/messaging/messaging-spans.md | 49 +----------------------- model/registry/deprecated/messaging.yaml | 11 ++++++ model/registry/messaging.yaml | 12 ------ model/trace/messaging.yaml | 21 ---------- 6 files changed, 38 insertions(+), 106 deletions(-) create mode 100644 .chloggen/1241.yaml diff --git a/.chloggen/1241.yaml b/.chloggen/1241.yaml new file mode 100644 index 0000000000..a3af4264c3 --- /dev/null +++ b/.chloggen/1241.yaml @@ -0,0 +1,4 @@ +change_type: breaking +component: messaging +note: Deprecate `messaging.destination_publish.*`` namespace and remove all usages. +issues: [ 1178, 1241 ] diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index e670a5e58f..47fff29b16 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -30,15 +30,13 @@ Attributes describing telemetry around messaging systems and messaging activitie | `messaging.destination.subscription.name` | string | The name of the destination subscription from which a message is consumed. [4] | `subscription-a` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [5] | `/customers/{customerId}` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.destination.temporary` | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.destination_publish.anonymous` | boolean | A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name). | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.destination_publish.name` | string | The name of the original destination the message was published to [6] | `MyQueue`; `MyTopic` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.message.body.size` | int | The size of the message body in bytes. [7] | `1439` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.message.body.size` | int | The size of the message body in bytes. [6] | `1439` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.message.conversation_id` | string | The conversation ID identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [8] | `2738` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [7] | `2738` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.operation.name` | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.operation.type` | string | A string identifying the type of the messaging operation. [9] | `publish`; `create`; `receive` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `messaging.system` | string | The messaging system as identified by the client instrumentation. [10] | `activemq`; `aws_sqs`; `eventgrid` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.operation.type` | string | A string identifying the type of the messaging operation. [8] | `publish`; `create`; `receive` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.system` | string | The messaging system as identified by the client instrumentation. [9] | `activemq`; `aws_sqs`; `eventgrid` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs. @@ -51,18 +49,15 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi **[5]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. -**[6]:** The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If -the broker doesn't have such notion, the original destination name SHOULD uniquely identify the broker. - -**[7]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed +**[6]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed body size should be used. -**[8]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed +**[7]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed size should be used. -**[9]:** If a custom value is used, it MUST be of low cardinality. +**[8]:** If a custom value is used, it MUST be of low cardinality. -**[10]:** The actual messaging system may differ from the one known by the client. For example, when using Kafka client libraries to communicate with Azure Event Hubs, the `messaging.system` is set to `kafka` based on the instrumentation's best knowledge. +**[9]:** The actual messaging system may differ from the one known by the client. For example, when using Kafka client libraries to communicate with Azure Event Hubs, the `messaging.system` is set to `kafka` based on the instrumentation's best knowledge. `messaging.operation.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. @@ -116,11 +111,11 @@ This group describes attributes specific to Apache Kafka. | Attribute | Type | Description | Examples | Stability | | ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------- | -| `messaging.kafka.message.key` | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [11] | `myKey` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.kafka.message.key` | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [10] | `myKey` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.kafka.message.tombstone` | boolean | A boolean that is true if the message is a tombstone. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `messaging.kafka.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[11]:** If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value. +**[10]:** If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value. ## RabbitMQ Attributes @@ -185,13 +180,15 @@ This group describes attributes specific to Azure Service Bus. Describes deprecated messaging attributes. -| Attribute | Type | Description | Examples | Stability | -| ---------------------------------------------------- | ------ | ----------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `messaging.client_id` | string | Deprecated, use `messaging.client.id` instead. | `client-5`; `myhost@8742@s8083jm` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.client.id`. | -| `messaging.eventhubs.consumer.group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `$Default` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name`. | -| `messaging.kafka.consumer.group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `my-group` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name`. | -| `messaging.kafka.destination.partition` | int | Deprecated, use `messaging.destination.partition.id` instead. | `2` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.destination.partition.id`. | -| `messaging.kafka.message.offset` | int | Deprecated, use `messaging.kafka.offset` instead. | `42` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.kafka.offset`. | -| `messaging.operation` | string | Deprecated, use `messaging.operation.type` instead. | `publish`; `create`; `process` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.operation.type`. | -| `messaging.rocketmq.client_group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `myConsumerGroup` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name` on the consumer spans. No replacement for producer spans. | -| `messaging.servicebus.destination.subscription_name` | string | Deprecated, use `messaging.servicebus.destination.subscription_name` instead. | `subscription-a` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.servicebus.destination.subscription_name`. | +| Attribute | Type | Description | Examples | Stability | +| ---------------------------------------------------- | ------- | ----------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `messaging.client_id` | string | Deprecated, use `messaging.client.id` instead. | `client-5`; `myhost@8742@s8083jm` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.client.id`. | +| `messaging.destination_publish.anonymous` | boolean | Deprecated, no replacement at this time. | | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
No replacement at this time. | +| `messaging.destination_publish.name` | string | Deprecated, no replacement at this time. | `MyQueue`; `MyTopic` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
No replacement at this time. | +| `messaging.eventhubs.consumer.group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `$Default` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name`. | +| `messaging.kafka.consumer.group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `my-group` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name`. | +| `messaging.kafka.destination.partition` | int | Deprecated, use `messaging.destination.partition.id` instead. | `2` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.destination.partition.id`. | +| `messaging.kafka.message.offset` | int | Deprecated, use `messaging.kafka.offset` instead. | `42` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.kafka.offset`. | +| `messaging.operation` | string | Deprecated, use `messaging.operation.type` instead. | `publish`; `create`; `process` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.operation.type`. | +| `messaging.rocketmq.client_group` | string | Deprecated, use `messaging.consumer.group.name` instead. | `myConsumerGroup` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.consumer.group.name` on the consumer spans. No replacement for producer spans. | +| `messaging.servicebus.destination.subscription_name` | string | Deprecated, use `messaging.servicebus.destination.subscription_name` instead. | `subscription-a` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.servicebus.destination.subscription_name`. | diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 0855774bcf..d2d00ae79e 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -26,7 +26,6 @@ - [Producer spans](#producer-spans) - [Consumer spans](#consumer-spans) - [Messaging attributes](#messaging-attributes) - - [Consumer attributes](#consumer-attributes) - [Recording per-message attributes on batch operations](#recording-per-message-attributes-on-batch-operations) - [Examples](#examples) - [Topic with multiple consumers](#topic-with-multiple-consumers) @@ -89,12 +88,6 @@ A destination is usually uniquely identified by its name within the messaging system instance. Examples of a destination name would be an URL or a simple one-word identifier. -In some use cases, messages are routed within one or multiple brokers. In such -cases, the destination the message was originally published to is different -from the destination it is being consumed from. When information about the -destination where the message was originally published to is available, consumers -can record them under the `destination_publish` namespace. - Typical examples of destinations include Kafka topics, RabbitMQ queues and topics. ### Message consumption @@ -288,9 +281,8 @@ Messaging attributes are organized into the following namespaces: - `messaging.message`: Contains attributes that describe individual messages. - `messaging.destination`: Contains attributes that describe the logical entity messages are published to. See [Destinations](#destinations) for more details. -- `messaging.destination_publish`: Contains attributes that describe the logical entity messages were originally published to. See [Destinations](#destinations) for more details. - `messaging.batch`: Contains attributes that describe batch operations. -- `messaging.consumer`: Contains [consumer attributes](#consumer-attributes) that describe the application instance that consumes a message. See [consumer](#consumer) for more details. +- `messaging.consumer`: Contains attributes that describe the application instance that consumes a message. See [Consumer](#consumer) for more details. Messaging system-specific attributes MUST be defined in the corresponding `messaging.{system}` namespace. @@ -436,45 +428,6 @@ and SHOULD be provided **at span creation time** (if provided at all): - - - - - -### Consumer attributes - -The following additional attributes describe message consumer operations. - -Since messages could be routed by brokers, the destination messages are published -to may not match with the destination they are consumed from. - -If information about the original destination is available on the consumer, -consumer instrumentations SHOULD populate the attributes -under the namespace `messaging.destination_publish.*` - - - - - - - - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`messaging.destination_publish.anonymous`](/docs/attributes-registry/messaging.md) | boolean | A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name). | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.destination_publish.name`](/docs/attributes-registry/messaging.md) | string | The name of the original destination the message was published to [1] | `MyQueue`; `MyTopic` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If -the broker doesn't have such notion, the original destination name SHOULD uniquely identify the broker. - - - -The following attributes can be important for making sampling decisions -and SHOULD be provided **at span creation time** (if provided at all): - -* [`messaging.destination_publish.name`](/docs/attributes-registry/messaging.md) - - diff --git a/model/registry/deprecated/messaging.yaml b/model/registry/deprecated/messaging.yaml index f7144862db..8054a9e1ae 100644 --- a/model/registry/deprecated/messaging.yaml +++ b/model/registry/deprecated/messaging.yaml @@ -65,3 +65,14 @@ groups: examples: 42 deprecated: > Replaced by `messaging.kafka.offset`. + - id: messaging.destination_publish.anonymous + type: boolean + stability: experimental + brief: 'Deprecated, no replacement at this time.' + deprecated: "No replacement at this time." + - id: messaging.destination_publish.name + type: string + stability: experimental + brief: 'Deprecated, no replacement at this time.' + deprecated: "No replacement at this time." + examples: ['MyQueue', 'MyTopic'] diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index 7a06243fc4..f17e8cb5bd 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -65,18 +65,6 @@ groups: type: boolean stability: experimental brief: 'A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed.' - - id: destination_publish.anonymous - type: boolean - stability: experimental - brief: 'A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name).' - - id: destination_publish.name - type: string - stability: experimental - brief: 'The name of the original destination the message was published to' - note: | - The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If - the broker doesn't have such notion, the original destination name SHOULD uniquely identify the broker. - examples: ['MyQueue', 'MyTopic'] - id: destination.partition.id type: string stability: experimental diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index 0d3c9f067d..c429f7a542 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -1,25 +1,4 @@ groups: - - id: messaging.destination_publish - prefix: messaging.destination_publish - type: attribute_group - brief: > - Semantic convention for attributes that describe the publish messaging destination on broker. - The term Publish Destination refers to the destination the message was originally published to. - These attributes should be used on the consumer side when information about - the publish destination is available and different than the destination message are consumed from. - note: | - Publish destination attributes should be set on publish, receive, - or other spans describing messaging operations. - Destination attributes should be set when the messaging operation handles - single messages. When the operation handles a batch of messages, - the destination attributes should only be applied when the attribute value - applies to all messages in the batch. - In other cases, destination attributes may be set on links. - attributes: - - ref: messaging.destination_publish.name - sampling_relevant: true - - ref: messaging.destination_publish.anonymous - - id: attributes.messaging.trace.minimal type: attribute_group brief: > From c7fe07e542ac8d7fd1270b5df551d1b2619d00ce Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 15 Jul 2024 16:17:06 -0700 Subject: [PATCH 22/23] db.query.text IN-clauses MAY be collapsed during the sanitization process (#1243) Co-authored-by: Liudmila Molkova --- .chloggen/1243.yaml | 22 ++++++++++++++++++++++ docs/database/database-spans.md | 4 ++++ 2 files changed, 26 insertions(+) create mode 100644 .chloggen/1243.yaml diff --git a/.chloggen/1243.yaml b/.chloggen/1243.yaml new file mode 100644 index 0000000000..321a3dc7f4 --- /dev/null +++ b/.chloggen/1243.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: db + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: "`db.query.text` IN-clauses MAY be collapsed during the sanitization process" + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [ 1053 ] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 3a38d4def6..c9f164ab49 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -250,6 +250,10 @@ in which case the instrumentation MAY choose a different placeholder. Placeholders in a parameterized query SHOULD not be sanitized. E.g. `where id = $1` can be captured as is. +[IN-clauses](https://en.wikipedia.org/wiki/Where_(SQL)#IN) MAY be collapsed during sanitization, +e.g. from `IN (?, ?, ?, ?)` to `IN (?)`, as this can help with extremely long IN-clauses, +and can help control cardinality for users who choose to (optionally) add `db.query.text` to their metric attributes. + ## Semantic Conventions for specific database technologies More specific Semantic Conventions are defined for the following database technologies: From 02ecf0c71e9fa74d09d81c48e04a132db2b7060b Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Tue, 16 Jul 2024 09:13:08 +0200 Subject: [PATCH 23/23] CloudEvents should re-use existing HTTP or messaging conventions (#1182) --- .chloggen/cloud-events-restructure.yaml | 5 + docs/cloudevents/cloudevents-spans.md | 170 ++---------------------- 2 files changed, 14 insertions(+), 161 deletions(-) create mode 100755 .chloggen/cloud-events-restructure.yaml diff --git a/.chloggen/cloud-events-restructure.yaml b/.chloggen/cloud-events-restructure.yaml new file mode 100755 index 0000000000..90e15f3bc9 --- /dev/null +++ b/.chloggen/cloud-events-restructure.yaml @@ -0,0 +1,5 @@ +change_type: 'enhancement' +component: cloudevents +note: CloudEvents conventions to follow HTTP/Messaging Span conventions +issues: [654] +subtext: diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md index ca5ea0d0e6..79672b8e15 100644 --- a/docs/cloudevents/cloudevents-spans.md +++ b/docs/cloudevents/cloudevents-spans.md @@ -11,12 +11,8 @@ linkTitle: CloudEvents Spans - [Definitions](#definitions) -- [Overview](#overview) - [Conventions](#conventions) - - [Spans](#spans) - - [Creation](#creation) - - [Processing](#processing) - - [Attributes](#attributes) +- [Span attributes](#span-attributes) @@ -35,168 +31,20 @@ consult the [CloudEvents Primer](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/primer.md) document. -## Overview - -A CloudEvent can be sent directly from producer to consumer. -For such a scenario, the traditional parent-child trace model works well. -However, CloudEvents are also used in distributed systems where an event -can go through many [hops](https://en.wikipedia.org/wiki/Hop_%28networking%29) -until it reaches a consumer. In this scenario, the traditional parent-child -trace model is not sufficient to produce a meaningful trace. - -Consider the following scenario: - -``` -+----------+ +--------------+ -| Producer | ---------------> | Intermediary | -+----------+ +--------------+ - | - | - | - v -+----------+ +----------+ -| Consumer | <----------------- | Queue | -+----------+ +----------+ -``` - -With the traditional parent-child trace model, the above scenario would produce -two traces, completely independent from each other because the consumer -starts receiving (and thus has to specify a parent span) before it receives the event. -It is not possible to correlate a producer with a consumer(s) solely via a parent-child relationship. - -``` -+-------------------------------------------------+ -| Trace 1 | -| | -| +---------------------------------------+ | -| | Send (auto-instr) | | -| +---------------------------------------+ | -| +------------------------------------+ | -| | Intermediary: Received (auto-instr)| | -| +------------------------------------+ | -| +------------------------------------+ | -| | Intermediary: Send (auto-instr) | | -| +------------------------------------+ | -| | -| Trace 2 | -| | -| +---------------------------------------+ | -| | Consumer: Receive (auto-instr) | | -| +---------------------------------------+ | -| | -+-------------------------------------------------+ -``` - -This document defines semantic conventions to model the different stages -a CloudEvent can go through in a system, making it possible to create traces -that are meaningful and consistent. It covers creation, processing, -context propagation between producer and consumer(s) and attributes -to be added to spans. - -With the proposed model, it is possible to have an overview of everything -that happened as the result of an event. One can, for example, answer the -following questions: - -- What components in a system reacted to an event -- What further events were sent due to an incoming event -- Which event caused the exception - -With the conventions in this document, the application scenario above would -produce a trace where it is possible to correlate a producer with a consumer(s): - -``` -+-------------------------------------------------------+ -| Trace 1 | -| | -| +---------------------------------------+ | -| +---> | Create event | | -| | +---------------------------------------+ | -| | +---------------------------------------+ | -| | | Send (auto-instr) | | -| | +---------------------------------------+ | -| | +------------------------------------+ | -| | | Intermediary: Received (auto-instr)| | -| | +------------------------------------+ | -| | +------------------------------------+ | -| | | Intermediary: Send (auto-instr) | | -| |Link +------------------------------------+ | -| | | -| | | -| | | -| | Trace 2 | -| | | -| | +---------------------------------------+ | -| | | Consumer: Receive (auto-instr) | | -| | +---------------------------------------+ | -| | +-------------------------------------+ | -| +------ | Consumer: Process | | -| +-------------------------------------+ | -| | -+-------------------------------------------------------+ -``` - ## Conventions -To achieve the trace above, it is necessary to capture the context of -the event creation so that when the CloudEvent reaches its destination(s), this -context can be continued. Each CloudEvent acts then as the medium of this -context propagation. - -This document relies on the CloudEvents specification, which defines this -context propagation mechanism via the -[CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/extensions/distributed-tracing.md). -Once the trace context is set on the event -via the Distributed Tracing Extension, it MUST not be modified. - -The remainder of this section describes the semantic conventions for Spans -required to achieve the proposed trace. - -### Spans +CloudEvent-specific instrumentations SHOULD follow the span structure described in +the [Semantic Conventions for Messaging Spans](../messaging/messaging-spans.md). -#### Creation - -Instrumentation SHOULD create a new span and populate the +If CloudEvents are instrumented independently of the above conventions, +instrumentations can rely on the [CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/extensions/distributed-tracing.md) -on the event. This applies when: - -- A CloudEvent is created by the instrumented library. - It may be impossible or impractical to create the Span during event - creation (e.g. inside the constructor or in a factory method), - so instrumentation MAY create the Span later, when passing the event to the transport layer. -- A CloudEvent is created outside of the instrumented library - (e.g. directly constructed by the application owner, without calling a constructor or factory method), - and passed without the Distributed Tracing Extension populated. - -In case a CloudEvent is passed to the instrumented library with the -Distributed Tracing Extension already populated, instrumentation MUST NOT create -a span and MUST NOT modify the Distributed Tracing Extension on the event. - -- Span name: `CloudEvents Create ` - -- Span kind: PRODUCER - -- Span attributes: Instrumentation MUST add the required attributes defined - in the [table below](#attributes). - -#### Processing - -When an instrumented library supports processing of a single CloudEvent, -instrumentation SHOULD create a new span to trace it. - -Instrumentation SHOULD set the remote trace context from the -Distributed Tracing Extension as a link on the processing span. -Instrumentation MAY add attributes to the link to further describe it. - -- Span name: `CloudEvents Process ` - -- Span kind: CONSUMER - -- Span attributes: Instrumentation MUST add the required attributes defined - in the [table below](#attributes). +as means to propagate the trace context. -### Attributes +## Span attributes -The following attributes are applicable to creation and processing Spans. +Additionally, instrumentations may record the following CloudEvent-specific +attributes on spans created from the conventions described above.