Semantic Conventions for Database Metrics
Status: Experimental
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.
Connection pools
The following metric instruments describe database client connection pool operations.
Metric: db.client.connections.usage
This metric is required.
| 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 |
| 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 doesn’t provide a name, then the db.connection_string should be used | myDataSource | Required |
state | string | The state of a connection in the pool | idle | Required |
state MUST be one of the following:
| Value | Description |
|---|
idle | idle |
used | used |
Metric: db.client.connections.idle.max
This metric is recommended.
| Name | Instrument Type | Unit (UCUM) | Description |
|---|
db.client.connections.idle.max | UpDownCounter | {connection} | The maximum 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 doesn’t provide a name, then the db.connection_string should be used | myDataSource | Required |
Metric: db.client.connections.idle.min
This metric is recommended.
| 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 doesn’t provide a name, then the db.connection_string should be used | myDataSource | Required |
Metric: db.client.connections.max
This metric is recommended.
| 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 doesn’t provide a name, then the db.connection_string should be used | myDataSource | Required |
Metric: db.client.connections.pending_requests
This metric is recommended.
| 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 doesn’t provide a name, then the db.connection_string should be used | myDataSource | Required |
Metric: db.client.connections.timeouts
This metric is recommended.
| 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 doesn’t provide a name, then the db.connection_string should be used | myDataSource | Required |
Metric: db.client.connections.create_time
This metric is recommended.
| 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 doesn’t provide a name, then the db.connection_string should be used | myDataSource | Required |
Metric: db.client.connections.wait_time
This metric is recommended.
| 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 doesn’t provide a name, then the db.connection_string should be used | myDataSource | Required |
Metric: db.client.connections.use_time
This metric is recommended.
| 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 doesn’t provide a name, then the db.connection_string should be used | myDataSource | Required |