From 65651b8afff0c402d8fc04e654d078caae8ffd42 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 12 Jul 2024 08:28:02 -0700 Subject: [PATCH 1/5] Database client migration guide --- .../migration-guide.md | 249 ++++++++++++++++++ 1 file changed, 249 insertions(+) create mode 100644 docs/database/supplementary-guidelines/migration-guide.md diff --git a/docs/database/supplementary-guidelines/migration-guide.md b/docs/database/supplementary-guidelines/migration-guide.md new file mode 100644 index 0000000000..908fbd8d3e --- /dev/null +++ b/docs/database/supplementary-guidelines/migration-guide.md @@ -0,0 +1,249 @@ +# Database semantic convention stability migration guide + +Due to the significant number of modifications and the extensive user base +affected by them, existing database instrumentations published by +OpenTelemetry are required to implement a migration plan that will assist users in +transitioning to the stable database semantic conventions. + +Specifically, when existing database instrumentations published by OpenTelemetry are +updated to the stable database semantic conventions, they: + +- SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` in + their existing major version, which accepts: + - `database` - emit the stable database conventions, and stop emitting + the old database conventions that the instrumentation emitted previously. + - `database/dup` - emit both the old and the stable database conventions, + allowing for a phased rollout of the stable semantic conventions. + - The default behavior (in the absence of one of these values) is to continue + emitting whatever version of the old database conventions the + instrumentation was emitting previously. +- Need to maintain (security patching at a minimum) their existing major version + for at least six months after it starts emitting both sets of conventions. +- May drop the environment variable in their next major version and emit only + the stable database conventions. + +## Summary of changes + +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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/README.md). + +### Database client span attributes + + +| Change | Comments | +|-----------------------------------------------------|-------------------------------------------------------------------------------------------------------------| +| `db.connection_string` | Removed | +| `db.user` | Removed | +| `network.transport` | Removed | +| `network.type` | Removed | +| `db.name` | Removed, integrated into the new `db.namespace` | +| `db.redis.database_index` | Removed, integrated into the new `db.namespace` | +| `db.mssql.instance_name` | Removed, integrated into the new `db.namespace` | +| `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.cassandra.table` → `db.collection.name` | | +| `db.mongodb.collection` → `db.collection.name` | | +| `db.cosmosdb.container` → `db.collection.name` | | +| New: `db.query.parameter.` | Opt-In | +| New: `error.type` | | + + +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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/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) + +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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/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.TODO](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientoperationduration). + +### Experimental connection metrics + +Database connection metrics are still experimental, but there have been several changes in the latest + +#### Database client connection count + +Metric changes: + +- **Name**: `db.client.connections.usage` → `db.client.connection.count` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | +| `state` → `db.client.connection.state` | | + + +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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectioncount) + +#### Database client connection idle max + +Metric changes: + +- **Name**: `db.client.connections.idle.max` → `db.client.connection.idle.max` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | + + +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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectionidlemax) + +#### Database client connection idle min + +Metric changes: + +- **Name**: `db.client.connections.idle.min` → `db.client.connection.idle.min` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | + + +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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectionidlemin) + +#### Database client connection max + +Metric changes: + +- **Name**: `db.client.connections.max` → `db.client.connection.max` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | + + +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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectionmax) + +#### Database client connection pending requests + +Metric changes: + +- **Name**: `db.client.connections.pending_requests` → `db.client.connection.pending_requests` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | + + +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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectionpending_requests) + +#### Database client connection timeouts + +Metric changes: + +- **Name**: `db.client.connections.timeouts` → `db.client.connection.timeouts` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | + + +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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectiontimeouts) + +#### Database client connection create time + +Metric changes: + +- **Name**: `db.client.connections.create_time` → `db.client.connection.create_time` +- **Unit**: `ms` → `s` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | + + +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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectioncreate_time) + +#### Database client connection wait time + +Metric changes: + +- **Name**: `db.client.connections.wait_time` → `db.client.connection.wait_time` +- **Unit**: `ms` → `s` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | + + +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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectionwait_time) + +#### Database client connection use time + +Metric changes: + +- **Name**: `db.client.connections.use_time` → `db.client.connection.use_time` +- **Unit**: `ms` → `s` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | + + +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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectionuse_time) From 2557cd5af945fd3d40360e96a1b80b0291ffdf19 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 16 Aug 2024 08:10:53 -0700 Subject: [PATCH 2/5] Move file --- .../migration-guide.md => non-normative/db-migration.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{database/supplementary-guidelines/migration-guide.md => non-normative/db-migration.md} (100%) diff --git a/docs/database/supplementary-guidelines/migration-guide.md b/docs/non-normative/db-migration.md similarity index 100% rename from docs/database/supplementary-guidelines/migration-guide.md rename to docs/non-normative/db-migration.md From 98f5710bde7e623325ef6ce643c7812ff7517be4 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 16 Aug 2024 08:11:40 -0700 Subject: [PATCH 3/5] consistency --- docs/non-normative/db-migration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/non-normative/db-migration.md b/docs/non-normative/db-migration.md index 908fbd8d3e..76dbb0bca5 100644 --- a/docs/non-normative/db-migration.md +++ b/docs/non-normative/db-migration.md @@ -63,8 +63,8 @@ References: 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. +- `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) References: From da5829f30d6580884b6990b0f94f22ad85aeaf13 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 16 Aug 2024 08:12:44 -0700 Subject: [PATCH 4/5] finish sentence --- docs/non-normative/db-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/non-normative/db-migration.md b/docs/non-normative/db-migration.md index 76dbb0bca5..706c1225da 100644 --- a/docs/non-normative/db-migration.md +++ b/docs/non-normative/db-migration.md @@ -80,7 +80,7 @@ See [Metric `db.client.operation.duration` v1.TODO](https://github.com/open-tele ### Experimental connection metrics -Database connection metrics are still experimental, but there have been several changes in the latest +Database connection metrics are still experimental, but there have been several changes in the latest release. #### Database client connection count From 83dca89bfe480c6994f7112e594da7eb6060aa49 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 8 Oct 2024 11:14:35 -0700 Subject: [PATCH 5/5] Update to RC --- docs/non-normative/db-migration.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/non-normative/db-migration.md b/docs/non-normative/db-migration.md index 706c1225da..eee1011900 100644 --- a/docs/non-normative/db-migration.md +++ b/docs/non-normative/db-migration.md @@ -28,7 +28,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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/README.md). +[v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/README.md). ### Database client span attributes @@ -49,6 +49,8 @@ to | `db.cassandra.table` → `db.collection.name` | | | `db.mongodb.collection` → `db.collection.name` | | | `db.cosmosdb.container` → `db.collection.name` | | +| New: `db.operation.batch.size` | | +| New: `db.response.status_code` | | | New: `db.query.parameter.` | Opt-In | | New: `error.type` | | @@ -56,7 +58,7 @@ 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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/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 names @@ -70,13 +72,13 @@ that the operation is performed against and SHOULD adhere to one of the followin 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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-spans.md#name) +- [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 operation duration metric This is a required metric. There was no similar metric previously. -See [Metric `db.client.operation.duration` v1.TODO](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientoperationduration). +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). ### Experimental connection metrics @@ -99,7 +101,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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectioncount) +- [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) #### Database client connection idle max @@ -117,7 +119,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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectionidlemax) +- [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) #### Database client connection idle min @@ -135,7 +137,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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectionidlemin) +- [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) #### Database client connection max @@ -153,7 +155,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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectionmax) +- [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) #### Database client connection pending requests @@ -171,7 +173,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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectionpending_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) #### Database client connection timeouts @@ -189,7 +191,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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectiontimeouts) +- [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) #### Database client connection create time @@ -208,7 +210,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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectioncreate_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) #### Database client connection wait time @@ -227,7 +229,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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectionwait_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) #### Database client connection use time @@ -246,4 +248,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.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientconnectionuse_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)