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.

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:

NameInstrumentUnitUnit (UCUM)Description
db.client.connections.usageUpDownCounterconnections{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:

NameTypeDescriptionExamplesRequirement Level
statestringThe state of a connection in the pool. Valid values include: idle, used.idleRequired

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.

NameInstrument (*)UnitUnit (UCUM)Description
db.client.connections.idle.maxUpDownCounterconnections{connection}The maximum number of idle open connections allowed.
db.client.connections.idle.minUpDownCounterconnections{connection}The minimum number of idle open connections allowed.
db.client.connections.maxUpDownCounterconnections{connection}The maximum number of open connections allowed.
db.client.connections.pending_requestsUpDownCounterrequests{request}The number of pending requests for an open connection, cumulative for the entire pool.
db.client.connections.timeoutsCountertimeouts{timeout}The number of connection timeouts that have occurred trying to obtain a connection from the pool.
db.client.connections.create_timeHistogrammillisecondsmsThe time it took to create a new connection.
db.client.connections.wait_timeHistogrammillisecondsmsThe time it took to obtain an open connection from the pool.
db.client.connections.use_timeHistogrammillisecondsmsThe 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:

NameTypeDescriptionExamplesRequirement Level
pool.namestringThe 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.myDataSourceRequired