From 2c42b95f2b1523169d17c6d0992fd8da6a6a29e4 Mon Sep 17 00:00:00 2001 From: Mateusz Rzeszutek Date: Tue, 19 Apr 2022 02:44:41 +0200 Subject: [PATCH] Database connection pool metrics semantic conventions (#2273) --- CHANGELOG.md | 2 + .../metrics/semantic_conventions/README.md | 1 + .../semantic_conventions/database-metrics.md | 57 +++++++++++++++++++ 3 files changed, 60 insertions(+) create mode 100644 specification/metrics/semantic_conventions/database-metrics.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 4a4ba583f0f..115137c4ab8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,8 @@ release. - Clarify SDK behavior when view conflicts are present ([#2462](/~https://github.com/open-telemetry/opentelemetry-specification/pull/2462)). +- Add database connection pool metrics semantic conventions + ([#2273](/~https://github.com/open-telemetry/opentelemetry-specification/pull/2273)). ### Logs diff --git a/specification/metrics/semantic_conventions/README.md b/specification/metrics/semantic_conventions/README.md index eb02009d4bb..941a354bf70 100644 --- a/specification/metrics/semantic_conventions/README.md +++ b/specification/metrics/semantic_conventions/README.md @@ -20,6 +20,7 @@ The following semantic conventions surrounding metrics are defined: * [HTTP](http-metrics.md): For HTTP client and server metrics. +* [Database](database-metrics.md): For SQL and NoSQL client metrics. * [System](system-metrics.md): For standard system metrics. * [Process](process-metrics.md): For standard process metrics. * [Runtime Environment](runtime-environment-metrics.md): For runtime environment metrics. diff --git a/specification/metrics/semantic_conventions/database-metrics.md b/specification/metrics/semantic_conventions/database-metrics.md new file mode 100644 index 00000000000..9ab0443cfcd --- /dev/null +++ b/specification/metrics/semantic_conventions/database-metrics.md @@ -0,0 +1,57 @@ +# General + +**Status**: [Experimental](../../document-status.md) + +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. + + + + + +- [Metric Instruments](#metric-instruments) + * [Connection pools](#connection-pools) + + + +## Metric Instruments + +The following metric instruments MUST be used to describe database client operations. They MUST be of the specified type +and units. + +### Connection pools + +Below is a table of database client connection pool metric instruments that MUST be used by connection pool +instrumentations: + +| Name | Instrument | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | +|-------------------------------|----------------------------|-------------|-------------------------------------------|-------------------------------------------------------------------------------------------| +| `db.client.connections.usage` | UpDownCounter | connections | `{connections}` | 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: + +| Name | Type | Description | Examples | Required | +|---------|--------|------------------------------------------------------------------------------|----------|----------| +| `state` | string | The state of a connection in the pool. Valid values include: `idle`, `used`. | `idle` | Yes | + +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. + +| Name | Instrument ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | +|------------------------------------------|----------------------------------------------|--------------|-------------------------------------------|---------------------------------------------------------------------------------------------------| +| `db.client.connections.idle.max` | UpDownCounter | connections | `{connections}` | The maximum number of idle open connections allowed. | +| `db.client.connections.idle.min` | UpDownCounter | connections | `{connections}` | The minimum number of idle open connections allowed. | +| `db.client.connections.max` | UpDownCounter | connections | `{connections}` | The maximum number of open connections allowed. | +| `db.client.connections.pending_requests` | UpDownCounter | requests | `{requests}` | The number of pending requests for an open connection, cumulative for the entire pool. | +| `db.client.connections.timeouts` | Counter | timeouts | `{timeouts}` | 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. | + +Below is a table of the attributes that MUST be included on all connection pool measurements: + +| Name | Type | Description | Examples | Required | +|-------------|--------|------------------------------------------------------------------------------|----------------|----------| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. | `myDataSource` | Yes |