Database connection pool metrics semantic conventions

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
 

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.

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.
+
+<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
+
+<!-- toc -->
+
+- [Metric Instruments](#metric-instruments)
+  * [Connection pools](#connection-pools)
+
+<!-- tocstop -->
+
+## 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` | Asynchronous 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      |