From 752af8442ee3dbea4921da39ae974869cfe5e7d9 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Sat, 29 Mar 2025 13:29:17 -0700 Subject: [PATCH] Update database migration guide with most recent couple of changes (#2036) Co-authored-by: Liudmila Molkova --- docs/non-normative/db-migration.md | 38 ++++++++++++++---------------- 1 file changed, 18 insertions(+), 20 deletions(-) diff --git a/docs/non-normative/db-migration.md b/docs/non-normative/db-migration.md index 1ec7ce73c..7ec5fa0a3 100644 --- a/docs/non-normative/db-migration.md +++ b/docs/non-normative/db-migration.md @@ -40,7 +40,7 @@ This section summarizes the changes made to the HTTP semantic conventions from [v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/README.md). to -[v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/README.md). +[v1.31.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.31.0/docs/database/README.md). ### Database client span attributes @@ -57,10 +57,11 @@ to | `db.instance.id` | Removed, replaced by `server.address` or integrated into `db.namespace` as appropriate | | `db.statement` → `db.query.text` | Clarified, SHOULD be collected by default only if there is sanitization that excludes sensitive information | | `db.operation` → `db.operation.name` | | -| `db.sql.table` → `db.collection.name` | | +| `db.sql.table` → `db.collection.name` | Should not be captured if extracting the value from `db.query.text` since there could be multiple | | `db.cassandra.table` → `db.collection.name` | | | `db.mongodb.collection` → `db.collection.name` | | | `db.cosmosdb.container` → `db.collection.name` | | +| New: `db.query.summary` | | | New: `db.operation.batch.size` | | | New: `db.response.status_code` | | | New: `db.operation.parameter.` | Opt-In | @@ -70,27 +71,24 @@ to References: - [Database client span attributes v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md) -- [Database client span attributes v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-spans.md) +- [Database client span attributes v1.31.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.31.0/docs/database/database-spans.md) ### Database client span names -The recommended span name has changed to `{db.operation.name} {target}`, where the `{target}` SHOULD describe the entity -that the operation is performed against and SHOULD adhere to one of the following values, provided they are accessible: - -- `db.collection.name` SHOULD be used for data manipulation operations or operations on database collections -- `db.namespace` SHOULD be used for operations on a specific database namespace -- `server.address:server.port` SHOULD be used for other operations not targeting any specific database(s) or collection(s) +The recommended span name has changed. +See [Database client span names v1.31.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.31.0/docs/database/database-spans.md#name) +for details on the new span name recommendation. References: - [Database client span names v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md) -- [Database client span names v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-spans.md#name) +- [Database client span names v1.31.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.31.0/docs/database/database-spans.md#name) ### Database client operation duration metric This is a required metric. There was no similar metric previously. -See [Metric `db.client.operation.duration` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientoperationduration). +See [Metric `db.client.operation.duration` v1.31.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.31.0/docs/database/database-metrics.md#metric-dbclientoperationduration). ### Experimental connection metrics @@ -113,7 +111,7 @@ Metric changes: References: - [Metric `db.client.connections.usage` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionsusage) -- [Metric `db.client.connection.count` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectioncount) +- [Metric `db.client.connection.count` v1.31.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.31.0/docs/database/database-metrics.md#metric-dbclientconnectioncount) #### Database client connection idle max @@ -131,7 +129,7 @@ Metric changes: References: - [Metric `db.client.connections.idle.max` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionsidlemax) -- [Metric `db.client.connection.idle.max` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectionidlemax) +- [Metric `db.client.connection.idle.max` v1.31.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.31.0/docs/database/database-metrics.md#metric-dbclientconnectionidlemax) #### Database client connection idle min @@ -149,7 +147,7 @@ Metric changes: References: - [Metric `db.client.connections.idle.min` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionsidlemin) -- [Metric `db.client.connection.idle.min` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectionidlemin) +- [Metric `db.client.connection.idle.min` v1.31.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.31.0/docs/database/database-metrics.md#metric-dbclientconnectionidlemin) #### Database client connection max @@ -167,7 +165,7 @@ Metric changes: References: - [Metric `db.client.connections.max` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionsmax) -- [Metric `db.client.connection.max` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectionmax) +- [Metric `db.client.connection.max` v1.31.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.31.0/docs/database/database-metrics.md#metric-dbclientconnectionmax) #### Database client connection pending requests @@ -185,7 +183,7 @@ Metric changes: References: - [Metric `db.client.connections.pending_requests` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionspending_requests) -- [Metric `db.client.connection.pending_requests` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectionpending_requests) +- [Metric `db.client.connection.pending_requests` v1.31.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.31.0/docs/database/database-metrics.md#metric-dbclientconnectionpending_requests) #### Database client connection timeouts @@ -203,7 +201,7 @@ Metric changes: References: - [Metric `db.client.connections.timeouts` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionstimeouts) -- [Metric `db.client.connection.timeouts` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectiontimeouts) +- [Metric `db.client.connection.timeouts` v1.31.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.31.0/docs/database/database-metrics.md#metric-dbclientconnectiontimeouts) #### Database client connection create time @@ -222,7 +220,7 @@ Metric changes: References: - [Metric `db.client.connections.create_time` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionscreate_time) -- [Metric `db.client.connection.create_time` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectioncreate_time) +- [Metric `db.client.connection.create_time` v1.31.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.31.0/docs/database/database-metrics.md#metric-dbclientconnectioncreate_time) #### Database client connection wait time @@ -241,7 +239,7 @@ Metric changes: References: - [Metric `db.client.connections.wait_time` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionswait_time) -- [Metric `db.client.connection.wait_time` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectionwait_time) +- [Metric `db.client.connection.wait_time` v1.31.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.31.0/docs/database/database-metrics.md#metric-dbclientconnectionwait_time) #### Database client connection use time @@ -260,4 +258,4 @@ Metric changes: References: - [Metric `db.client.connections.use_time` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionsuse_time) -- [Metric `db.client.connection.use_time` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectionuse_time) +- [Metric `db.client.connection.use_time` v1.31.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.31.0/docs/database/database-metrics.md#metric-dbclientconnectionuse_time)