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 |