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 does not 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 does not 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 does not 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 does not 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 does not 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 does not 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 does not 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 does not 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 does not provide a name, then the db.connection_string should be used myDataSource Required