From 21676b401384af917051abc588152946c8541c06 Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Mon, 12 Feb 2024 16:17:49 -0800 Subject: [PATCH 01/16] Add db.client.call.duration metric --- docs/database/database-metrics.md | 130 ++++++++++++++++++++++++++++ model/db-common.yaml | 36 ++++++++ model/metrics/database-metrics.yaml | 14 +++ 3 files changed, 180 insertions(+) create mode 100644 model/db-common.yaml diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 54c9e92927..a371a25fb8 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -15,6 +15,8 @@ and attributes but more may be added in the future. +- [Database call](#database-call) + * [Metric: `db.client.call.duration`](#metric-dbclientcallduration) - [Connection pools](#connection-pools) * [Metric: `db.client.connections.usage`](#metric-dbclientconnectionsusage) * [Metric: `db.client.connections.idle.max`](#metric-dbclientconnectionsidlemax) @@ -35,6 +37,134 @@ and attributes but more may be added in the future. > until a transition plan to the (future) stable semantic conventions has been published. > Conventions include, but are not limited to, attributes, metric and span names, and unit of measure. +## Database call + +### Metric: `db.client.call.duration` + +**Status**: [Experimental][DocumentStatus] + +This metric is [required][MetricRequired]. + +When this metric is reported alongside a database operation span, the metric value SHOULD be the same as the database operation span duration. + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advisory-parameters) +of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.call.duration` | Histogram | `s` | Duration of database client calls. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`db.connection_string`](../attributes-registry/db.md) | string | The connection string used to connect to the database. It is recommended to remove embedded credentials. | `Server=(localdb)\v11.0;Integrated Security=true;` | Recommended | +| [`db.instance.id`](../attributes-registry/db.md) | string | An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. | `mysql-e26b99z.example.com` | Recommended: If different from the `server.address` | +| [`db.name`](../attributes-registry/db.md) | string | This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | Conditionally Required: If applicable. | +| [`db.operation`](../attributes-registry/db.md) | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. [2] | `findAndModify`; `HMSET`; `SELECT` | Conditionally Required: If available. | +| [`db.system`](../attributes-registry/db.md) | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required | +| [`db.user`](../attributes-registry/db.md) | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | Conditionally Required: [7] | + +**[1]:** In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name). + +**[2]:** When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. + +**[3]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[4]:** The value SHOULD be normalized to lowercase. + +**[5]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[7]:** If using a port other than the default port for this DBMS and if `server.address` is set. + +`db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `other_sql` | Some other SQL database. Fallback only. See notes. | +| `mssql` | Microsoft SQL Server | +| `mssqlcompact` | Microsoft SQL Server Compact | +| `mysql` | MySQL | +| `oracle` | Oracle Database | +| `db2` | IBM Db2 | +| `postgresql` | PostgreSQL | +| `redshift` | Amazon Redshift | +| `hive` | Apache Hive | +| `cloudscape` | Cloudscape | +| `hsqldb` | HyperSQL DataBase | +| `progress` | Progress Database | +| `maxdb` | SAP MaxDB | +| `hanadb` | SAP HANA | +| `ingres` | Ingres | +| `firstsql` | FirstSQL | +| `edb` | EnterpriseDB | +| `cache` | InterSystems Caché | +| `adabas` | Adabas (Adaptable Database System) | +| `firebird` | Firebird | +| `derby` | Apache Derby | +| `filemaker` | FileMaker | +| `informix` | Informix | +| `instantdb` | InstantDB | +| `interbase` | InterBase | +| `mariadb` | MariaDB | +| `netezza` | Netezza | +| `pervasive` | Pervasive PSQL | +| `pointbase` | PointBase | +| `sqlite` | SQLite | +| `sybase` | Sybase | +| `teradata` | Teradata | +| `vertica` | Vertica | +| `h2` | H2 | +| `coldfusion` | ColdFusion IMQ | +| `cassandra` | Apache Cassandra | +| `hbase` | Apache HBase | +| `mongodb` | MongoDB | +| `redis` | Redis | +| `couchbase` | Couchbase | +| `couchdb` | CouchDB | +| `cosmosdb` | Microsoft Azure Cosmos DB | +| `dynamodb` | Amazon DynamoDB | +| `neo4j` | Neo4j | +| `geode` | Apache Geode | +| `elasticsearch` | Elasticsearch | +| `memcached` | Memcached | +| `cockroachdb` | CockroachDB | +| `opensearch` | OpenSearch | +| `clickhouse` | ClickHouse | +| `spanner` | Cloud Spanner | +| `trino` | Trino | + +`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 | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. | +| `unix` | Unix domain socket | + +`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + ## Connection pools The following metric instruments describe database client connection pool operations. diff --git a/model/db-common.yaml b/model/db-common.yaml new file mode 100644 index 0000000000..e06dc5e74c --- /dev/null +++ b/model/db-common.yaml @@ -0,0 +1,36 @@ +groups: + - id: attributes.db.common + type: attribute_group + brief: 'Describes Database attributes.' + attributes: + - ref: db.system + requirement_level: required + + - id: attributes.db.client + type: attribute_group + brief: 'Database Client attributes' + extends: attributes.db.common + attributes: + - ref: db.connection_string + - ref: db.user + - ref: db.name + requirement_level: + conditionally_required: If applicable. + - ref: db.operation + requirement_level: + conditionally_required: If available. + - ref: server.address + brief: > + Name of the database host. + - ref: server.port + requirement_level: + conditionally_required: If using a port other than the default port for this DBMS and if `server.address` is set. + - ref: network.peer.address + - ref: network.peer.port + requirement_level: + recommended: If `network.peer.address` is set. + - ref: network.transport + - ref: network.type + - ref: db.instance.id + requirement_level: + recommended: If different from the `server.address` diff --git a/model/metrics/database-metrics.yaml b/model/metrics/database-metrics.yaml index 3df6d86a2c..1ef70ea04f 100644 --- a/model/metrics/database-metrics.yaml +++ b/model/metrics/database-metrics.yaml @@ -1,4 +1,18 @@ groups: + - id: metric_attributes.db.client + type: attribute_group + brief: 'Database client attributes' + extends: attributes.db.client + + - id: metric.db.client.call.duration + type: metric + metric_name: db.client.call.duration + brief: "Duration of database client calls." + instrument: histogram + unit: "s" + stability: experimental + extends: metric_attributes.db.client + - id: attributes.db type: attribute_group brief: Describes Database attributes From 4edbf07d1140e9c3e5a0b10c1e4bf465257e9498 Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Mon, 12 Feb 2024 16:32:51 -0800 Subject: [PATCH 02/16] Update changelog --- .chloggen/735.yaml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 .chloggen/735.yaml diff --git a/.chloggen/735.yaml b/.chloggen/735.yaml new file mode 100644 index 0000000000..e28402e049 --- /dev/null +++ b/.chloggen/735.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: db + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add `db.client.operation.duration` metric + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [512] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: From fda47895a4783e40c6135b29f59eca5c9855e514 Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Tue, 13 Feb 2024 10:45:14 -0800 Subject: [PATCH 03/16] Change metric name, remove db.user and db.connection_string --- docs/database/database-metrics.md | 16 +++++++--------- model/db-common.yaml | 2 -- model/metrics/database-metrics.yaml | 6 +++--- 3 files changed, 10 insertions(+), 14 deletions(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index a371a25fb8..e36e6f763f 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -15,8 +15,8 @@ and attributes but more may be added in the future. -- [Database call](#database-call) - * [Metric: `db.client.call.duration`](#metric-dbclientcallduration) +- [Database operation](#database-operation) + * [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) - [Connection pools](#connection-pools) * [Metric: `db.client.connections.usage`](#metric-dbclientconnectionsusage) * [Metric: `db.client.connections.idle.max`](#metric-dbclientconnectionsidlemax) @@ -37,9 +37,9 @@ and attributes but more may be added in the future. > until a transition plan to the (future) stable semantic conventions has been published. > Conventions include, but are not limited to, attributes, metric and span names, and unit of measure. -## Database call +## Database operation -### Metric: `db.client.call.duration` +### Metric: `db.client.operation.duration` **Status**: [Experimental][DocumentStatus] @@ -51,21 +51,19 @@ This metric SHOULD be specified with [`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `db.client.call.duration` | Histogram | `s` | Duration of database client calls. | +| `db.client.operation.duration` | Histogram | `s` | Duration of database client operations. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`db.connection_string`](../attributes-registry/db.md) | string | The connection string used to connect to the database. It is recommended to remove embedded credentials. | `Server=(localdb)\v11.0;Integrated Security=true;` | Recommended | | [`db.instance.id`](../attributes-registry/db.md) | string | An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. | `mysql-e26b99z.example.com` | Recommended: If different from the `server.address` | | [`db.name`](../attributes-registry/db.md) | string | This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | Conditionally Required: If applicable. | | [`db.operation`](../attributes-registry/db.md) | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. [2] | `findAndModify`; `HMSET`; `SELECT` | Conditionally Required: If available. | | [`db.system`](../attributes-registry/db.md) | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required | -| [`db.user`](../attributes-registry/db.md) | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended | | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` | Recommended | diff --git a/model/db-common.yaml b/model/db-common.yaml index e06dc5e74c..ba0d784c5f 100644 --- a/model/db-common.yaml +++ b/model/db-common.yaml @@ -11,8 +11,6 @@ groups: brief: 'Database Client attributes' extends: attributes.db.common attributes: - - ref: db.connection_string - - ref: db.user - ref: db.name requirement_level: conditionally_required: If applicable. diff --git a/model/metrics/database-metrics.yaml b/model/metrics/database-metrics.yaml index 1ef70ea04f..6a93f75f48 100644 --- a/model/metrics/database-metrics.yaml +++ b/model/metrics/database-metrics.yaml @@ -4,10 +4,10 @@ groups: brief: 'Database client attributes' extends: attributes.db.client - - id: metric.db.client.call.duration + - id: metric.db.client.operation.duration type: metric - metric_name: db.client.call.duration - brief: "Duration of database client calls." + metric_name: db.client.operation.duration + brief: "Duration of database client operations." instrument: histogram unit: "s" stability: experimental From 15c7dd804ea05084e4b4b3be139f7def541ce63d Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Mon, 8 Apr 2024 10:37:24 -0700 Subject: [PATCH 04/16] Adjust histogram bounds --- docs/database/database-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 02274d74d3..2362ebaadd 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -49,7 +49,7 @@ When this metric is reported alongside a database operation span, the metric val This metric SHOULD be specified with [`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advisory-parameters) -of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. +of `[ 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. | Name | Instrument Type | Unit (UCUM) | Description | From 3183aafdc191401e37e052607e6081a76e4c0d19 Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Mon, 8 Apr 2024 10:59:33 -0700 Subject: [PATCH 05/16] Rename db.operation -> db.operation.name --- model/db-common.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/model/db-common.yaml b/model/db-common.yaml index ba0d784c5f..2dff526f99 100644 --- a/model/db-common.yaml +++ b/model/db-common.yaml @@ -14,9 +14,11 @@ groups: - ref: db.name requirement_level: conditionally_required: If applicable. - - ref: db.operation + - ref: db.operation.name requirement_level: - conditionally_required: If available. + conditionally_required: > + If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture + `db.operation.name`, then it SHOULD be the first operation name found in the query. - ref: server.address brief: > Name of the database host. From f5c13c9a0ad25ff153c057544174315f62bba313 Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Mon, 8 Apr 2024 11:01:19 -0700 Subject: [PATCH 06/16] make table-generation --- docs/database/database-metrics.md | 194 +++++++++++++++--------------- 1 file changed, 97 insertions(+), 97 deletions(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 2362ebaadd..f943654e87 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -52,115 +52,115 @@ This metric SHOULD be specified with of `[ 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `db.client.operation.duration` | Histogram | `s` | Duration of database client operations. | +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.client.operation.duration` | Histogram | `s` | Duration of database client operations. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`db.instance.id`](../attributes-registry/db.md) | string | An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. | `mysql-e26b99z.example.com` | Recommended: If different from the `server.address` | -| [`db.name`](../attributes-registry/db.md) | string | This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | Conditionally Required: If applicable. | -| [`db.operation`](../attributes-registry/db.md) | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. [2] | `findAndModify`; `HMSET`; `SELECT` | Conditionally Required: If available. | -| [`db.system`](../attributes-registry/db.md) | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required | -| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | -| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` | Recommended | -| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | Conditionally Required: [7] | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`db.system`](../attributes-registry/db.md) | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.name`](../attributes-registry/db.md) | string | This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](../attributes-registry/db.md) | string | The name of the operation or command being executed. | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` [4] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.instance.id`](../attributes-registry/db.md) | string | An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. | `mysql-e26b99z.example.com` | `Recommended` If different from the `server.address` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` If `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [5] | `tcp`; `udp` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [6] | `ipv4`; `ipv6` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name). -**[2]:** When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. +**[2]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. + +**[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. -**[3]:** The value SHOULD be normalized to lowercase. +**[4]:** If using a port other than the default port for this DBMS and if `server.address` is set. + +**[5]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[4]:** The value SHOULD be normalized to lowercase. - -**[5]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. - -**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. - -**[7]:** If using a port other than the default port for this DBMS and if `server.address` is set. - -`db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. - -| Value | Description | -|---|---| -| `other_sql` | Some other SQL database. Fallback only. See notes. | -| `mssql` | Microsoft SQL Server | -| `mssqlcompact` | Microsoft SQL Server Compact | -| `mysql` | MySQL | -| `oracle` | Oracle Database | -| `db2` | IBM Db2 | -| `postgresql` | PostgreSQL | -| `redshift` | Amazon Redshift | -| `hive` | Apache Hive | -| `cloudscape` | Cloudscape | -| `hsqldb` | HyperSQL DataBase | -| `progress` | Progress Database | -| `maxdb` | SAP MaxDB | -| `hanadb` | SAP HANA | -| `ingres` | Ingres | -| `firstsql` | FirstSQL | -| `edb` | EnterpriseDB | -| `cache` | InterSystems Caché | -| `adabas` | Adabas (Adaptable Database System) | -| `firebird` | Firebird | -| `derby` | Apache Derby | -| `filemaker` | FileMaker | -| `informix` | Informix | -| `instantdb` | InstantDB | -| `interbase` | InterBase | -| `mariadb` | MariaDB | -| `netezza` | Netezza | -| `pervasive` | Pervasive PSQL | -| `pointbase` | PointBase | -| `sqlite` | SQLite | -| `sybase` | Sybase | -| `teradata` | Teradata | -| `vertica` | Vertica | -| `h2` | H2 | -| `coldfusion` | ColdFusion IMQ | -| `cassandra` | Apache Cassandra | -| `hbase` | Apache HBase | -| `mongodb` | MongoDB | -| `redis` | Redis | -| `couchbase` | Couchbase | -| `couchdb` | CouchDB | -| `cosmosdb` | Microsoft Azure Cosmos DB | -| `dynamodb` | Amazon DynamoDB | -| `neo4j` | Neo4j | -| `geode` | Apache Geode | -| `elasticsearch` | Elasticsearch | -| `memcached` | Memcached | -| `cockroachdb` | CockroachDB | -| `opensearch` | OpenSearch | -| `clickhouse` | ClickHouse | -| `spanner` | Cloud Spanner | -| `trino` | Trino | - -`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 | -|---|---| -| `tcp` | TCP | -| `udp` | UDP | -| `pipe` | Named or anonymous pipe. | -| `unix` | Unix domain socket | - -`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. - -| Value | Description | -|---|---| -| `ipv4` | IPv4 | -| `ipv6` | IPv6 | +**[6]:** The value SHOULD be normalized to lowercase. + +**[7]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + +`db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `other_sql` | Some other SQL database. Fallback only. See notes. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mssql` | Microsoft SQL Server | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mssqlcompact` | Microsoft SQL Server Compact | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mysql` | MySQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `oracle` | Oracle Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db2` | IBM Db2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `postgresql` | PostgreSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `redshift` | Amazon Redshift | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hive` | Apache Hive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cloudscape` | Cloudscape | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hsqldb` | HyperSQL DataBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `progress` | Progress Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `maxdb` | SAP MaxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hanadb` | SAP HANA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ingres` | Ingres | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `firstsql` | FirstSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `edb` | EnterpriseDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `adabas` | Adabas (Adaptable Database System) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `firebird` | Firebird | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `derby` | Apache Derby | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `filemaker` | FileMaker | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `informix` | Informix | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `instantdb` | InstantDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interbase` | InterBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mariadb` | MariaDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `netezza` | Netezza | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pervasive` | Pervasive PSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pointbase` | PointBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `sqlite` | SQLite | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `sybase` | Sybase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `teradata` | Teradata | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vertica` | Vertica | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `h2` | H2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `coldfusion` | ColdFusion IMQ | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cassandra` | Apache Cassandra | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hbase` | Apache HBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `redis` | Redis | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `couchbase` | Couchbase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `couchdb` | CouchDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cosmosdb` | Microsoft Azure Cosmos DB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dynamodb` | Amazon DynamoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `geode` | Apache Geode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `elasticsearch` | Elasticsearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cockroachdb` | CockroachDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `opensearch` | OpenSearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `clickhouse` | ClickHouse | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `spanner` | Cloud Spanner | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `trino` | Trino | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ## Connection pools From 4eb06ab4bb18a384ad44ef0f1a912f6a6fb1d024 Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Mon, 8 Apr 2024 12:38:13 -0700 Subject: [PATCH 07/16] Add db.collection.name attribute --- model/db-common.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/model/db-common.yaml b/model/db-common.yaml index 2dff526f99..c152dd4b12 100644 --- a/model/db-common.yaml +++ b/model/db-common.yaml @@ -14,6 +14,11 @@ groups: - ref: db.name requirement_level: conditionally_required: If applicable. + - ref: db.collection.name + requirement_level: + conditionally_required: > + If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture + `db.collection.name`, then it SHOULD be the first collection name found in the query. - ref: db.operation.name requirement_level: conditionally_required: > From 98a126606fdbbd029d11a54c321e674119a420af Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Mon, 8 Apr 2024 12:38:25 -0700 Subject: [PATCH 08/16] make table-generation --- docs/database/database-metrics.md | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index f943654e87..6c9e54f5c1 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -61,33 +61,38 @@ of `[ 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.system`](../attributes-registry/db.md) | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.name`](../attributes-registry/db.md) | string | This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](../attributes-registry/db.md) | string | The name of the operation or command being executed. | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.port`](../attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Conditionally Required` [4] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.collection.name`](../attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.name`](../attributes-registry/db.md) | string | This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [3] | `customers`; `main` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](../attributes-registry/db.md) | string | The name of the operation or command being executed. | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [5] | `80`; `8080`; `443` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.instance.id`](../attributes-registry/db.md) | string | An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. | `mysql-e26b99z.example.com` | `Recommended` If different from the `server.address` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` If `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [5] | `tcp`; `udp` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [6] | `ipv4`; `ipv6` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [7] | `tcp`; `udp` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [8] | `ipv4`; `ipv6` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name). +**[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. -**[2]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. +**[2]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.collection.name`, then it SHOULD be the first collection name found in the query. -**[3]:** When 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]:** In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name). -**[4]:** If using a port other than the default port for this DBMS and if `server.address` is set. +**[4]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. -**[5]:** The value SHOULD be normalized to lowercase. +**[5]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[6]:** If using a port other than the default port for this DBMS and if `server.address` is set. + +**[7]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[6]:** The value SHOULD be normalized to lowercase. +**[8]:** The value SHOULD be normalized to lowercase. -**[7]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +**[9]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. `db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. From 9f0acb32dda255953c17defc307474e992247d9f Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Mon, 8 Apr 2024 12:39:26 -0700 Subject: [PATCH 09/16] Add 0.001 bucket --- docs/database/database-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 6c9e54f5c1..6eac246069 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -49,7 +49,7 @@ When this metric is reported alongside a database operation span, the metric val This metric SHOULD be specified with [`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advisory-parameters) -of `[ 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. +of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. | Name | Instrument Type | Unit (UCUM) | Description | Stability | From 265f2d57a4d3e27001cd638c72c59e5f3f10d945 Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Mon, 8 Apr 2024 13:22:22 -0700 Subject: [PATCH 10/16] Update model/db-common.yaml Co-authored-by: Trask Stalnaker --- model/db-common.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/model/db-common.yaml b/model/db-common.yaml index c152dd4b12..9b6edf0eac 100644 --- a/model/db-common.yaml +++ b/model/db-common.yaml @@ -34,8 +34,6 @@ groups: - ref: network.peer.port requirement_level: recommended: If `network.peer.address` is set. - - ref: network.transport - - ref: network.type - ref: db.instance.id requirement_level: recommended: If different from the `server.address` From 90c1961f42190ca4bf84b7e79a2f600986b386dd Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Mon, 8 Apr 2024 13:23:15 -0700 Subject: [PATCH 11/16] make table-generation --- docs/database/database-metrics.md | 30 ++---------------------------- 1 file changed, 2 insertions(+), 28 deletions(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 6eac246069..e3661f3d4b 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -68,9 +68,7 @@ of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. | [`db.instance.id`](../attributes-registry/db.md) | string | An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. | `mysql-e26b99z.example.com` | `Recommended` If different from the `server.address` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` If `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [7] | `tcp`; `udp` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [8] | `ipv4`; `ipv6` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.address`](../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) | +| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. @@ -84,15 +82,7 @@ of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. **[6]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[7]:** The value SHOULD be normalized to lowercase. - -Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport. For example -different processes could be listening on TCP port 12345 and UDP port 12345. - -**[8]:** The value SHOULD be normalized to lowercase. - -**[9]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +**[7]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. `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. @@ -150,22 +140,6 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | `clickhouse` | ClickHouse | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `spanner` | Cloud Spanner | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `trino` | Trino | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -|---|---|---| -| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - -`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -|---|---|---| -| `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ## Connection pools From 1a17fe758bdc577d2ae48ab683363689f7d65b10 Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Mon, 8 Apr 2024 13:30:43 -0700 Subject: [PATCH 12/16] make markdown-toc --- docs/database/database-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index e3661f3d4b..2fef13f9c0 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -16,7 +16,7 @@ and attributes but more may be added in the future. - [Database operation](#database-operation) - * [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) + - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) - [Connection pools](#connection-pools) - [Metric: `db.client.connections.usage`](#metric-dbclientconnectionsusage) - [Metric: `db.client.connections.idle.max`](#metric-dbclientconnectionsidlemax) From e54bbc84a8e4a550b64c332d1ce2075b0d19e539 Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Fri, 19 Apr 2024 10:01:52 -0700 Subject: [PATCH 13/16] make table-generation --- docs/database/database-metrics.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index bb593b6632..37a80415df 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -66,9 +66,9 @@ of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. | [`db.operation.name`](../attributes-registry/db.md) | string | The name of the operation or command being executed. | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.port`](../attributes-registry/server.md) | int | Server port number. [5] | `80`; `8080`; `443` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.instance.id`](../attributes-registry/db.md) | string | An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. | `mysql-e26b99z.example.com` | `Recommended` If different from the `server.address` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` If `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [7] | `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`](../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`](../attributes-registry/server.md) | string | Name of the database host. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. @@ -82,7 +82,10 @@ of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. **[6]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[7]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +**[7]:** Semantic conventions for individual database systems SHOULD document whether `network.peer.*` attributes are applicable. Network peer address and port are useful when the application interacts with individual database nodes directly. +If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. + +**[8]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. `db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. From 3a629a5a6d68c42b0ab0e6b9312b82fa646c9b46 Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Fri, 19 Apr 2024 10:04:15 -0700 Subject: [PATCH 14/16] Revert minor change to db-common.yaml --- model/db-common.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/model/db-common.yaml b/model/db-common.yaml index 2158cf8fa8..fdefe67883 100644 --- a/model/db-common.yaml +++ b/model/db-common.yaml @@ -3,8 +3,6 @@ groups: type: attribute_group brief: 'Database Client attributes' attributes: - - ref: db.system - requirement_level: required - ref: db.name requirement_level: conditionally_required: If applicable. @@ -21,6 +19,8 @@ groups: conditionally_required: > If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. + - ref: db.system + requirement_level: required - ref: network.peer.address brief: Peer address of the database node where the operation was performed. requirement_level: From e755f154c5c697f2469d4a42f317e67e7aa0d061 Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Fri, 19 Apr 2024 10:14:28 -0700 Subject: [PATCH 15/16] Remove unnecessary attribute_group --- model/metrics/database-metrics.yaml | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/model/metrics/database-metrics.yaml b/model/metrics/database-metrics.yaml index 54005a8d42..ec8f61c55c 100644 --- a/model/metrics/database-metrics.yaml +++ b/model/metrics/database-metrics.yaml @@ -1,9 +1,4 @@ groups: - - id: metric_attributes.db.client - type: attribute_group - brief: 'Database client attributes' - extends: attributes.db.client - - id: metric.db.client.operation.duration type: metric metric_name: db.client.operation.duration @@ -11,7 +6,7 @@ groups: instrument: histogram unit: "s" stability: experimental - extends: metric_attributes.db.client + extends: attributes.db.client - id: metric.db.client.connections.usage type: metric From f739c72e40fb7fe40ff5aba079f6f41b9aecf6b7 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 22 Apr 2024 15:44:52 -0700 Subject: [PATCH 16/16] Update docs/database/database-metrics.md --- docs/database/database-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 37a80415df..ccf76a54b1 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -48,7 +48,7 @@ This metric is [required][MetricRequired]. When this metric is reported alongside a database operation span, the metric value SHOULD be the same as the database operation span duration. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`.