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.

Warning Existing database instrumentations that are using v1.24.0 of this document (or prior) SHOULD NOT change the version of the database conventions that they emit until a transition plan to the (future) stable semantic conventions has been published. Conventions include, but are not limited to, attributes, metric and span names, and unit of measure.

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	Stability
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	Stability
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, instrumentation should use a combination of server.address and server.port attributes formatted as server.address:server.port.	myDataSource	Required
state	string	The state of a connection in the pool	idle	Required

state MUST be one of the following:

Value	Description	Stability
idle	idle
used	used

Metric: db.client.connections.idle.max

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
db.client.connections.idle.max	UpDownCounter	{connection}	The maximum number of idle open connections allowed

Attribute	Type	Description	Examples	Requirement Level	Stability
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, instrumentation should use a combination of server.address and server.port attributes formatted as server.address:server.port.	myDataSource	Required

Metric: db.client.connections.idle.min

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
db.client.connections.idle.min	UpDownCounter	{connection}	The minimum number of idle open connections allowed

Attribute	Type	Description	Examples	Requirement Level	Stability
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, instrumentation should use a combination of server.address and server.port attributes formatted as server.address:server.port.	myDataSource	Required

Metric: db.client.connections.max

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
db.client.connections.max	UpDownCounter	{connection}	The maximum number of open connections allowed

Attribute	Type	Description	Examples	Requirement Level	Stability
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, instrumentation should use a combination of server.address and server.port attributes formatted as server.address:server.port.	myDataSource	Required

Metric: db.client.connections.pending_requests

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
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	Stability
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, instrumentation should use a combination of server.address and server.port attributes formatted as server.address:server.port.	myDataSource	Required

Metric: db.client.connections.timeouts

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
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	Stability
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, instrumentation should use a combination of server.address and server.port attributes formatted as server.address:server.port.	myDataSource	Required

Metric: db.client.connections.create_time

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
db.client.connections.create_time	Histogram	ms	The time it took to create a new connection

Attribute	Type	Description	Examples	Requirement Level	Stability
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, instrumentation should use a combination of server.address and server.port attributes formatted as server.address:server.port.	myDataSource	Required

Metric: db.client.connections.wait_time

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
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	Stability
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, instrumentation should use a combination of server.address and server.port attributes formatted as server.address:server.port.	myDataSource	Required

Metric: db.client.connections.use_time

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
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	Stability
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, instrumentation should use a combination of server.address and server.port attributes formatted as server.address:server.port.	myDataSource	Required