From 7803036e14d1408965f48cf6aabd639272bf8885 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Tue, 6 Jun 2023 18:42:22 +0200 Subject: [PATCH] Generate database metric semconv from yaml --- .../metrics/database-metrics.yaml | 107 ++++++++++ specification/database/database-metrics.md | 191 +++++++++++++++--- 2 files changed, 265 insertions(+), 33 deletions(-) create mode 100644 semantic_conventions/metrics/database-metrics.yaml diff --git a/semantic_conventions/metrics/database-metrics.yaml b/semantic_conventions/metrics/database-metrics.yaml new file mode 100644 index 0000000000..28bf0131ee --- /dev/null +++ b/semantic_conventions/metrics/database-metrics.yaml @@ -0,0 +1,107 @@ +groups: + - id: attributes.db + type: attribute_group + brief: Describes Database attributes + attributes: + - id: state + type: + allow_custom_values: false + members: + - id: idle + value: 'idle' + - id: used + value: 'used' + requirement_level: required + brief: "The state of a connection in the pool" + examples: ["idle"] + - id: pool.name + type: string + requirement_level: required + brief: > + The name of the connection pool; unique within the instrumented application. + In case the connection pool implementation does not provide a name, + then the [db.connection_string](/specification/trace/semantic_conventions/database.md#connection-level-attributes) + should be used + examples: ["myDataSource"] + + - id: metric.db.client.connections.usage + type: metric + metric_name: db.client.connections.usage + brief: "The number of connections that are currently in state described by the `state` attribute" + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: state + - ref: pool.name + + - id: metric.db.client.connections.idle.max + type: metric + metric_name: db.client.connections.idle.max + brief: "The maximum number of idle open connections allowed" + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: pool.name + + - id: metric.db.client.connections.idle.min + type: metric + metric_name: db.client.connections.idle.min + brief: "The minimum number of idle open connections allowed" + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: pool.name + + - id: metric.db.client.connections.max + type: metric + metric_name: db.client.connections.max + brief: "The maximum number of open connections allowed" + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: pool.name + + - id: metric.db.client.connections.pending_requests + type: metric + metric_name: db.client.connections.pending_requests + brief: "The number of pending requests for an open connection, cumulative for the entire pool" + instrument: updowncounter + unit: "{request}" + attributes: + - ref: pool.name + + - id: metric.db.client.connections.timeouts + type: metric + metric_name: db.client.connections.timeouts + brief: "The number of connection timeouts that have occurred trying to obtain a connection from the pool" + instrument: counter + unit: "{timeout}" + attributes: + - ref: pool.name + + - id: metric.db.client.connections.create_time + type: metric + metric_name: db.client.connections.create_time + brief: "The time it took to create a new connection" + instrument: histogram + unit: "ms" + attributes: + - ref: pool.name + + - id: metric.db.client.connections.wait_time + type: metric + metric_name: db.client.connections.wait_time + brief: "The time it took to obtain an open connection from the pool" + instrument: histogram + unit: "ms" + attributes: + - ref: pool.name + + - id: metric.db.client.connections.use_time + type: metric + metric_name: db.client.connections.use_time + brief: "The time between borrowing a connection and returning it to the pool" + instrument: histogram + unit: "ms" + attributes: + - ref: pool.name diff --git a/specification/database/database-metrics.md b/specification/database/database-metrics.md index 42ca828e63..737124847c 100644 --- a/specification/database/database-metrics.md +++ b/specification/database/database-metrics.md @@ -8,56 +8,181 @@ linkTitle: Database The conventions described in this section are specific to SQL and NoSQL clients. -**Disclaimer:** These are initial database client metric instruments and attributes but more may be added in the future. +**Disclaimer:** These are initial database client metric instruments +and attributes but more may be added in the future. -- [Metric Instruments](#metric-instruments) - * [Connection pools](#connection-pools) +- [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 Instruments +## Connection pools -The following metric instruments MUST be used to describe database client operations. They MUST be of the specified type -and units. +The following metric instruments describe database client connection pool operations. -### Connection pools +### Metric: `db.client.connections.usage` -Below is a table of database client connection pool metric instruments that MUST be used by connection pool -instrumentations: +This metric is [required][MetricRequired]. -| Name | Instrument | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description | -|-------------------------------|----------------------------|-------------|-------------------------------------------|-------------------------------------------------------------------------------------------| -| `db.client.connections.usage` | UpDownCounter | connections | `{connection}` | The number of connections that are currently in state described by the `state` attribute. | + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.usage` | UpDownCounter | `{connection}` | The number of connections that are currently in state described by the `state` attribute | + -All `db.client.connections.usage` measurements MUST include the following attribute: + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/specification/trace/semantic_conventions/database.md#connection-level-attributes) should be used | `myDataSource` | Required | +| `state` | string | The state of a connection in the pool | `idle` | Required | -| Name | Type | Description | Examples | Requirement Level | -|---------|--------|------------------------------------------------------------------------------|----------|-------------------| -| `state` | string | The state of a connection in the pool. Valid values include: `idle`, `used`. | `idle` | Required | +`state` MUST be one of the following: -Instrumentation libraries for database client connection pools that collect data for the following data MUST use the -following metric instruments. Otherwise, if the instrumentation library does not collect this data, these instruments -MUST NOT be used. +| Value | Description | +|---|---| +| `idle` | idle | +| `used` | used | + +### Metric: `db.client.connections.idle.max` -| Name | Instrument ([*](/specification/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description | -|------------------------------------------|----------------------------------------------|--------------|-------------------------------------------|---------------------------------------------------------------------------------------------------| -| `db.client.connections.idle.max` | UpDownCounter | connections | `{connection}` | The maximum number of idle open connections allowed. | -| `db.client.connections.idle.min` | UpDownCounter | connections | `{connection}` | The minimum number of idle open connections allowed. | -| `db.client.connections.max` | UpDownCounter | connections | `{connection}` | The maximum number of open connections allowed. | -| `db.client.connections.pending_requests` | UpDownCounter | requests | `{request}` | The number of pending requests for an open connection, cumulative for the entire pool. | -| `db.client.connections.timeouts` | Counter | timeouts | `{timeout}` | The number of connection timeouts that have occurred trying to obtain a connection from the pool. | -| `db.client.connections.create_time` | Histogram | milliseconds | `ms` | The time it took to create a new connection. | -| `db.client.connections.wait_time` | Histogram | milliseconds | `ms` | The time it took to obtain an open connection from the pool. | -| `db.client.connections.use_time` | Histogram | milliseconds | `ms` | The time between borrowing a connection and returning it to the pool. | +This metric is [recommended][MetricRecommended]. -Below is a table of the attributes that MUST be included on all connection pool measurements: + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.idle.max` | UpDownCounter | `{connection}` | The maximum number of idle open connections allowed | + -| Name | Type | Description | Examples | Requirement Level | -|-------------|--------|------------------------------------------------------------------------------|----------------|-------------------| -| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/specification/database/database-spans.md#connection-level-attributes) should be used. | `myDataSource` | Required | + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/specification/trace/semantic_conventions/database.md#connection-level-attributes) should be used | `myDataSource` | Required | + + +### Metric: `db.client.connections.idle.min` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.idle.min` | UpDownCounter | `{connection}` | The minimum number of idle open connections allowed | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/specification/trace/semantic_conventions/database.md#connection-level-attributes) should be used | `myDataSource` | Required | + + +### Metric: `db.client.connections.max` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.max` | UpDownCounter | `{connection}` | The maximum number of open connections allowed | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/specification/trace/semantic_conventions/database.md#connection-level-attributes) should be used | `myDataSource` | Required | + + +### Metric: `db.client.connections.pending_requests` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.pending_requests` | UpDownCounter | `{request}` | The number of pending requests for an open connection, cumulative for the entire pool | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/specification/trace/semantic_conventions/database.md#connection-level-attributes) should be used | `myDataSource` | Required | + + +### Metric: `db.client.connections.timeouts` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.timeouts` | Counter | `{timeout}` | The number of connection timeouts that have occurred trying to obtain a connection from the pool | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/specification/trace/semantic_conventions/database.md#connection-level-attributes) should be used | `myDataSource` | Required | + + +### Metric: `db.client.connections.create_time` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.create_time` | Histogram | `ms` | The time it took to create a new connection | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/specification/trace/semantic_conventions/database.md#connection-level-attributes) should be used | `myDataSource` | Required | + + +### Metric: `db.client.connections.wait_time` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.wait_time` | Histogram | `ms` | The time it took to obtain an open connection from the pool | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/specification/trace/semantic_conventions/database.md#connection-level-attributes) should be used | `myDataSource` | Required | + + +### Metric: `db.client.connections.use_time` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.use_time` | Histogram | `ms` | The time between borrowing a connection and returning it to the pool | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/specification/trace/semantic_conventions/database.md#connection-level-attributes) should be used | `myDataSource` | Required | + [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[MetricRequired]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/metrics/metric-requirement-level.md#required +[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/metrics/metric-requirement-level.md#recommended