数据库度量的语义约定

NOTICE Semantic Conventions are moving to a new location.

No changes to this document are allowed.

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
• Connection pools

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:

Name	Instrument	Unit	Unit (UCUM)	Description
db.client.connections.usage	UpDownCounter	connections	{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:

Name	Type	Description	Examples	Requirement Level
state	string	The state of a connection in the pool. Valid values include: idle, used.	idle	Required

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.

Name	Instrument (*)	Unit	Unit (UCUM)	Description
db.client.connections.idle.max	UpDownCounter	connections	{connection}	The maximum number of idle open connections allowed.
db.client.connections.idle.min	UpDownCounter	connections	{connection}	The minimum number of idle open connections allowed.
db.client.connections.max	UpDownCounter	connections	{connection}	The maximum number of open connections allowed.
db.client.connections.pending_requests	UpDownCounter	requests	{request}	The number of pending requests for an open connection, cumulative for the entire pool.
db.client.connections.timeouts	Counter	timeouts	{timeout}	The number of connection timeouts that have occurred trying to obtain a connection from the pool.
db.client.connections.create_time	Histogram	milliseconds	ms	The time it took to create a new connection.
db.client.connections.wait_time	Histogram	milliseconds	ms	The time it took to obtain an open connection from the pool.
db.client.connections.use_time	Histogram	milliseconds	ms	The 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:

Name	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