diff --git a/.chloggen/db_client_connection_metric.yaml b/.chloggen/db_client_connection_metric.yaml new file mode 100755 index 0000000000..0c3c9222d8 --- /dev/null +++ b/.chloggen/db_client_connection_metric.yaml @@ -0,0 +1,24 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: breaking + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: db + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: > + Rename `db.client.connections.*` metric namespace to `db.client.connection.*` and + rename `db.client.connection.usage` to `db.client.connection.count`. + +# 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: [201, 967] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index dbace71ea0..4350081a1d 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -18,15 +18,15 @@ and attributes but more may be added in the future. - [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) - - [Metric: `db.client.connections.idle.min`](#metric-dbclientconnectionsidlemin) - - [Metric: `db.client.connections.max`](#metric-dbclientconnectionsmax) - - [Metric: `db.client.connections.pending_requests`](#metric-dbclientconnectionspending_requests) - - [Metric: `db.client.connections.timeouts`](#metric-dbclientconnectionstimeouts) - - [Metric: `db.client.connections.create_time`](#metric-dbclientconnectionscreate_time) - - [Metric: `db.client.connections.wait_time`](#metric-dbclientconnectionswait_time) - - [Metric: `db.client.connections.use_time`](#metric-dbclientconnectionsuse_time) + - [Metric: `db.client.connection.count`](#metric-dbclientconnectioncount) + - [Metric: `db.client.connection.idle.max`](#metric-dbclientconnectionidlemax) + - [Metric: `db.client.connection.idle.min`](#metric-dbclientconnectionidlemin) + - [Metric: `db.client.connection.max`](#metric-dbclientconnectionmax) + - [Metric: `db.client.connection.pending_requests`](#metric-dbclientconnectionpending_requests) + - [Metric: `db.client.connection.timeouts`](#metric-dbclientconnectiontimeouts) + - [Metric: `db.client.connection.create_time`](#metric-dbclientconnectioncreate_time) + - [Metric: `db.client.connection.wait_time`](#metric-dbclientconnectionwait_time) + - [Metric: `db.client.connection.use_time`](#metric-dbclientconnectionuse_time) @@ -158,17 +158,17 @@ If a database operation involved multiple network calls (for example retries), t The following metric instruments describe database client connection pool operations. -### Metric: `db.client.connections.usage` +### Metric: `db.client.connection.count` This metric is [required][MetricRequired]. - + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.client.connections.usage` | UpDownCounter | `{connection}` | The number of connections that are currently in state described by the `state` attribute | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.connection.count` | UpDownCounter | `{connection}` | The number of connections that are currently in state described by the `state` attribute | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.client.connections.pool.name`](/docs/attributes-registry/db.md) | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -181,129 +181,129 @@ This metric is [required][MetricRequired]. | `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `used` | used | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### Metric: `db.client.connections.idle.max` +### Metric: `db.client.connection.idle.max` This metric is [recommended][MetricRecommended]. - + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.client.connections.idle.max` | UpDownCounter | `{connection}` | The maximum number of idle open connections allowed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.connection.idle.max` | UpDownCounter | `{connection}` | The maximum number of idle open connections allowed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.client.connections.pool.name`](/docs/attributes-registry/db.md) | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### Metric: `db.client.connections.idle.min` +### Metric: `db.client.connection.idle.min` This metric is [recommended][MetricRecommended]. - + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.client.connections.idle.min` | UpDownCounter | `{connection}` | The minimum number of idle open connections allowed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.connection.idle.min` | UpDownCounter | `{connection}` | The minimum number of idle open connections allowed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.client.connections.pool.name`](/docs/attributes-registry/db.md) | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### Metric: `db.client.connections.max` +### Metric: `db.client.connection.max` This metric is [recommended][MetricRecommended]. - + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.client.connections.max` | UpDownCounter | `{connection}` | The maximum number of open connections allowed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.connection.max` | UpDownCounter | `{connection}` | The maximum number of open connections allowed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.client.connections.pool.name`](/docs/attributes-registry/db.md) | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### Metric: `db.client.connections.pending_requests` +### Metric: `db.client.connection.pending_requests` This metric is [recommended][MetricRecommended]. - + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.client.connections.pending_requests` | UpDownCounter | `{request}` | The number of pending requests for an open connection, cumulative for the entire pool | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.connection.pending_requests` | UpDownCounter | `{request}` | The number of pending requests for an open connection, cumulative for the entire pool | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.client.connections.pool.name`](/docs/attributes-registry/db.md) | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### Metric: `db.client.connections.timeouts` +### Metric: `db.client.connection.timeouts` This metric is [recommended][MetricRecommended]. - + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.client.connections.timeouts` | Counter | `{timeout}` | The number of connection timeouts that have occurred trying to obtain a connection from the pool | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.connection.timeouts` | Counter | `{timeout}` | The number of connection timeouts that have occurred trying to obtain a connection from the pool | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.client.connections.pool.name`](/docs/attributes-registry/db.md) | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### Metric: `db.client.connections.create_time` +### Metric: `db.client.connection.create_time` This metric is [recommended][MetricRecommended]. - + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.client.connections.create_time` | Histogram | `ms` | The time it took to create a new connection | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.connection.create_time` | Histogram | `s` | The time it took to create a new connection | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.client.connections.pool.name`](/docs/attributes-registry/db.md) | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### Metric: `db.client.connections.wait_time` +### Metric: `db.client.connection.wait_time` This metric is [recommended][MetricRecommended]. - + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.client.connections.wait_time` | Histogram | `ms` | The time it took to obtain an open connection from the pool | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.connection.wait_time` | Histogram | `s` | The time it took to obtain an open connection from the pool | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.client.connections.pool.name`](/docs/attributes-registry/db.md) | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### Metric: `db.client.connections.use_time` +### Metric: `db.client.connection.use_time` This metric is [recommended][MetricRecommended]. - + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.client.connections.use_time` | Histogram | `ms` | The time between borrowing a connection and returning it to the pool | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.connection.use_time` | Histogram | `s` | The time between borrowing a connection and returning it to the pool | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.client.connections.pool.name`](/docs/attributes-registry/db.md) | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/metrics/database-metrics.yaml b/model/metrics/database-metrics.yaml index ec8f61c55c..95f884f342 100644 --- a/model/metrics/database-metrics.yaml +++ b/model/metrics/database-metrics.yaml @@ -8,9 +8,9 @@ groups: stability: experimental extends: attributes.db.client - - id: metric.db.client.connections.usage + - id: metric.db.client.connection.count type: metric - metric_name: db.client.connections.usage + metric_name: db.client.connection.count stability: experimental brief: "The number of connections that are currently in state described by the `state` attribute" instrument: updowncounter @@ -21,9 +21,9 @@ groups: - ref: db.client.connections.pool.name requirement_level: required - - id: metric.db.client.connections.idle.max + - id: metric.db.client.connection.idle.max type: metric - metric_name: db.client.connections.idle.max + metric_name: db.client.connection.idle.max stability: experimental brief: "The maximum number of idle open connections allowed" instrument: updowncounter @@ -32,9 +32,9 @@ groups: - ref: db.client.connections.pool.name requirement_level: required - - id: metric.db.client.connections.idle.min + - id: metric.db.client.connection.idle.min type: metric - metric_name: db.client.connections.idle.min + metric_name: db.client.connection.idle.min stability: experimental brief: "The minimum number of idle open connections allowed" instrument: updowncounter @@ -43,9 +43,9 @@ groups: - ref: db.client.connections.pool.name requirement_level: required - - id: metric.db.client.connections.max + - id: metric.db.client.connection.max type: metric - metric_name: db.client.connections.max + metric_name: db.client.connection.max stability: experimental brief: "The maximum number of open connections allowed" instrument: updowncounter @@ -54,9 +54,9 @@ groups: - ref: db.client.connections.pool.name requirement_level: required - - id: metric.db.client.connections.pending_requests + - id: metric.db.client.connection.pending_requests type: metric - metric_name: db.client.connections.pending_requests + metric_name: db.client.connection.pending_requests stability: experimental brief: "The number of pending requests for an open connection, cumulative for the entire pool" instrument: updowncounter @@ -65,9 +65,9 @@ groups: - ref: db.client.connections.pool.name requirement_level: required - - id: metric.db.client.connections.timeouts + - id: metric.db.client.connection.timeouts type: metric - metric_name: db.client.connections.timeouts + metric_name: db.client.connection.timeouts stability: experimental brief: "The number of connection timeouts that have occurred trying to obtain a connection from the pool" instrument: counter @@ -76,35 +76,35 @@ groups: - ref: db.client.connections.pool.name requirement_level: required - - id: metric.db.client.connections.create_time + - id: metric.db.client.connection.create_time type: metric - metric_name: db.client.connections.create_time + metric_name: db.client.connection.create_time stability: experimental brief: "The time it took to create a new connection" instrument: histogram - unit: "ms" + unit: "s" attributes: - ref: db.client.connections.pool.name requirement_level: required - - id: metric.db.client.connections.wait_time + - id: metric.db.client.connection.wait_time type: metric - metric_name: db.client.connections.wait_time + metric_name: db.client.connection.wait_time stability: experimental brief: "The time it took to obtain an open connection from the pool" instrument: histogram - unit: "ms" + unit: "s" attributes: - ref: db.client.connections.pool.name requirement_level: required - - id: metric.db.client.connections.use_time + - id: metric.db.client.connection.use_time type: metric - metric_name: db.client.connections.use_time + metric_name: db.client.connection.use_time stability: experimental brief: "The time between borrowing a connection and returning it to the pool" instrument: histogram - unit: "ms" + unit: "s" attributes: - ref: db.client.connections.pool.name requirement_level: required diff --git a/model/metrics/deprecated/database.yaml b/model/metrics/deprecated/database.yaml new file mode 100644 index 0000000000..5e6332294f --- /dev/null +++ b/model/metrics/deprecated/database.yaml @@ -0,0 +1,110 @@ +groups: + - id: metric.db.client.connections.count.deprecated + type: metric + metric_name: db.client.connections.usage + stability: experimental + deprecated: "Replaced by `db.client.connection.count`." + brief: "Deprecated, use `db.client.connection.count` instead." + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: db.client.connections.state + requirement_level: required + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connections.idle.max.deprecated + type: metric + metric_name: db.client.connections.idle.max + stability: experimental + deprecated: "Replaced by `db.client.connection.idle.max`." + brief: "Deprecated, use `db.client.connection.idle.max` instead." + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connections.idle.min.deprecated + type: metric + metric_name: db.client.connections.idle.min + stability: experimental + deprecated: "Replaced by `db.client.connection.idle.min`." + brief: "Deprecated, use `db.client.connection.idle.min` instead." + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connections.max.deprecated + type: metric + metric_name: db.client.connections.max + stability: experimental + deprecated: "Replaced by `db.client.connection.max`." + brief: "Deprecated, use `db.client.connection.max` instead." + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connections.pending_requests.deprecated + type: metric + metric_name: db.client.connections.pending_requests + stability: experimental + deprecated: "Replaced by `db.client.connection.pending_requests`." + brief: "Deprecated, use `db.client.connection.pending_requests` instead." + instrument: updowncounter + unit: "{request}" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connections.timeouts.deprecated + type: metric + metric_name: db.client.connections.timeouts + stability: experimental + deprecated: "Replaced by `db.client.connection.timeouts`." + brief: "Deprecated, use `db.client.connection.timeouts` instead." + instrument: counter + unit: "{timeout}" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connections.create_time.deprecated + type: metric + metric_name: db.client.connections.create_time + stability: experimental + deprecated: "Replaced by `db.client.connection.create_time`. Note: the unit also changed from `ms` to `s`." + brief: "Deprecated, use `db.client.connection.create_time` instead. Note: the unit also changed from `ms` to `s`." + instrument: histogram + unit: "ms" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connections.wait_time.deprecated + type: metric + metric_name: db.client.connections.wait_time + stability: experimental + deprecated: "Replaced by `db.client.connection.wait_time`. Note: the unit also changed from `ms` to `s`." + brief: "Deprecated, use `db.client.connection.wait_time` instead. Note: the unit also changed from `ms` to `s`." + instrument: histogram + unit: "ms" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required + + - id: metric.db.client.connections.use_time.deprecated + type: metric + metric_name: db.client.connections.use_time + stability: experimental + deprecated: "Replaced by `db.client.connection.use_time`. Note: the unit also changed from `ms` to `s`." + brief: "Deprecated, use `db.client.connection.use_time` instead. Note: the unit also changed from `ms` to `s`." + instrument: histogram + unit: "ms" + attributes: + - ref: db.client.connections.pool.name + requirement_level: required diff --git a/schema-next.yaml b/schema-next.yaml index 85bfa85d72..e344c34056 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -4,6 +4,14 @@ versions: next: metrics: changes: + # https://github.com/open-telemetry/semantic-conventions/pull/966 + - rename_metrics: + db.client.connections.usage: db.client.connection.count + db.client.connections.idle.max: db.client.connection.idle.max + db.client.connections.idle.min: db.client.connection.idle.min + db.client.connections.max: db.client.connection.max + db.client.connections.pending_requests: db.client.connection.pending_requests + db.client.connections.timeouts: db.client.connection.timeouts # https://github.com/open-telemetry/semantic-conventions/pull/909 - rename_attributes: attribute_map: