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
  • Metric: db.client.connections.usage
  • Metric: db.client.connections.idle.max
  • Metric: db.client.connections.idle.min
  • Metric: db.client.connections.max
  • Metric: db.client.connections.pending_requests
  • Metric: db.client.connections.timeouts
  • Metric: db.client.connections.create_time
  • Metric: db.client.connections.wait_time
  • Metric: db.client.connections.use_time

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