DB

General Database Attributes

This group defines the attributes used to describe telemetry in the context of databases.

AttributeTypeDescriptionExamplesStability
db.client.connection.pool.namestringThe 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 parameters that would make the name unique, for example, combining attributes server.address, server.port, and db.namespace, formatted as server.address:server.port/db.namespace. Instrumentations that generate connection pool name following different patterns SHOULD document it.myDataSourceDevelopment
db.client.connection.statestringThe state of a connection in the poolidleDevelopment
db.collection.namestringThe name of a collection (table, container) within the database. [1]public.users; customersStable
db.namespacestringThe name of the database, fully qualified within the server address and port. [2]customers; test.usersStable
db.operation.batch.sizeintThe number of queries included in a batch operation. [3]2; 3; 4Stable
db.operation.namestringThe name of the operation or command being executed. [4]findAndModify; HMSET; SELECTStable
db.operation.parameter.<key>stringA database operation parameter, with <key> being the parameter name, and the attribute value being a string representation of the parameter value. [5]someval; 55Development
db.query.parameter.<key>stringA database query parameter, with <key> being the parameter name, and the attribute value being a string representation of the parameter value. [6]someval; 55Development
db.query.summarystringLow cardinality summary of a database query. [7]SELECT wuser_table; INSERT shipping_details SELECT orders; get user by idStable
db.query.textstringThe database query being executed. [8]SELECT * FROM wuser_table where username = ?; SET mykey ?Stable
db.response.returned_rowsintNumber of rows returned by the operation.10; 30; 1000Development
db.response.status_codestringDatabase response status code. [9]102; ORA-17002; 08P01; 404Stable
db.stored_procedure.namestringThe name of a stored procedure within the database. [10]GetCustomerStable
db.system.namestringThe database management system (DBMS) product as identified by the client instrumentation. [11]other_sql; softwareag.adabas; actian.ingresStable

[1] db.collection.name: It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.

The collection name SHOULD NOT be extracted from db.query.text, when the database system supports query text with multiple collections in non-batch operations.

For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used.

[2] db.namespace: If a database system has multiple namespace components, they SHOULD be concatenated from the most general to the most specific namespace component, using | as a separator between the components. Any missing components (and their associated separators) SHOULD be omitted. Semantic conventions for individual database systems SHOULD document what db.namespace means in the context of that system. It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.

[3] db.operation.batch.size: Operations are only considered batches when they contain two or more operations, and so db.operation.batch.size SHOULD never be 1.

[4] db.operation.name: It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.

The operation name SHOULD NOT be extracted from db.query.text, when the database system supports query text with multiple operations in non-batch operations.

If spaces can occur in the operation name, multiple consecutive spaces SHOULD be normalized to a single space.

For batch operations, if the individual operations are known to have the same operation name then that operation name SHOULD be used prepended by BATCH , otherwise db.operation.name SHOULD be BATCH or some other database system specific term if more applicable.

[5] db.operation.parameter.<key>: For example, a client-side maximum number of rows to read from the database MAY be recorded as the db.operation.parameter.max_rows attribute.

db.query.text parameters SHOULD be captured using db.query.parameter.<key> instead of db.operation.parameter.<key>.

[6] db.query.parameter.<key>: If a query parameter has no name and instead is referenced only by index, then <key> SHOULD be the 0-based index.

db.query.parameter.<key> SHOULD match up with the parameterized placeholders present in db.query.text.

db.query.parameter.<key> SHOULD NOT be captured on batch operations.

Examples:

  • For a query SELECT * FROM users where username = %s with the parameter "jdoe", the attribute db.query.parameter.0 SHOULD be set to "jdoe".

  • For a query "SELECT * FROM users WHERE username = %(username)s; with parameter username = "jdoe", the attribute db.query.parameter.username SHOULD be set to "jdoe".

[7] db.query.summary: The query summary describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.

Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following Generating query summary section.

[8] db.query.text: For sanitization see Sanitization of db.query.text. For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator ; or some other database system specific separator if more applicable. Parameterized query text SHOULD NOT be sanitized. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.

[9] db.response.status_code: The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what db.response.status_code means in the context of that system.

[10] db.stored_procedure.name: It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.

For batch operations, if the individual operations are known to have the same stored procedure name then that stored procedure name SHOULD be used.

[11] db.system.name: The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the db.system.name is set to postgresql based on the instrumentation’s best knowledge.


db.client.connection.state has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
idleidleDevelopment
usedusedDevelopment

db.system.name has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
actian.ingresActian IngresDevelopment
aws.dynamodbAmazon DynamoDBDevelopment
aws.redshiftAmazon RedshiftDevelopment
azure.cosmosdbAzure Cosmos DBDevelopment
cassandraApache CassandraDevelopment
clickhouseClickHouseDevelopment
cockroachdbCockroachDBDevelopment
couchbaseCouchbaseDevelopment
couchdbApache CouchDBDevelopment
derbyApache DerbyDevelopment
elasticsearchElasticsearchDevelopment
firebirdsqlFirebirdDevelopment
gcp.spannerGoogle Cloud SpannerDevelopment
geodeApache GeodeDevelopment
h2databaseH2 DatabaseDevelopment
hbaseApache HBaseDevelopment
hiveApache HiveDevelopment
hsqldbHyperSQL DatabaseDevelopment
ibm.db2IBM Db2Development
ibm.informixIBM InformixDevelopment
ibm.netezzaIBM NetezzaDevelopment
influxdbInfluxDBDevelopment
instantdbInstantDevelopment
intersystems.cacheInterSystems CachéDevelopment
mariadbMariaDBStable
memcachedMemcachedDevelopment
microsoft.sql_serverMicrosoft SQL ServerStable
mongodbMongoDBDevelopment
mysqlMySQLStable
neo4jNeo4jDevelopment
opensearchOpenSearchDevelopment
oracle.dbOracle DatabaseDevelopment
other_sqlSome other SQL database. Fallback only.Development
postgresqlPostgreSQLStable
redisRedisDevelopment
sap.hanaSAP HANADevelopment
sap.maxdbSAP MaxDBDevelopment
softwareag.adabasAdabas (Adaptable Database System)Development
sqliteSQLiteDevelopment
teradataTeradataDevelopment
trinoTrinoDevelopment

Deprecated Database Attributes

Describes deprecated database attributes.

AttributeTypeDescriptionExamplesStability
db.cassandra.consistency_levelstringDeprecated, use cassandra.consistency.level instead.all; each_quorum; quorumDeprecated
Replaced by cassandra.consistency.level.
db.cassandra.coordinator.dcstringDeprecated, use cassandra.coordinator.dc instead.us-west-2Deprecated
Replaced by cassandra.coordinator.dc.
db.cassandra.coordinator.idstringDeprecated, use cassandra.coordinator.id instead.be13faa2-8574-4d71-926d-27f16cf8a7afDeprecated
Replaced by cassandra.coordinator.id.
db.cassandra.idempotencebooleanDeprecated, use cassandra.query.idempotent instead.Deprecated
Replaced by cassandra.query.idempotent.
db.cassandra.page_sizeintDeprecated, use cassandra.page.size instead.5000Deprecated
Replaced by cassandra.page.size.
db.cassandra.speculative_execution_countintDeprecated, use cassandra.speculative_execution.count instead.0; 2Deprecated
Replaced by cassandra.speculative_execution.count.
db.cassandra.tablestringDeprecated, use db.collection.name instead.mytableDeprecated
Replaced by db.collection.name.
db.connection_stringstringDeprecated, use server.address, server.port attributes instead.Server=(localdb)\v11.0;Integrated Security=true;Deprecated
Replaced by server.address and server.port.
db.cosmosdb.client_idstringDeprecated, use azure.client.id instead.3ba4827d-4422-483f-b59f-85b74211c11dDeprecated
Replaced by azure.client.id.
db.cosmosdb.connection_modestringDeprecated, use azure.cosmosdb.connection.mode instead.gateway; directDeprecated
Replaced by azure.cosmosdb.connection.mode.
db.cosmosdb.consistency_levelstringDeprecated, use cosmosdb.consistency.level instead.Eventual; ConsistentPrefix; BoundedStaleness; Strong; SessionDeprecated
Replaced by azure.cosmosdb.consistency.level.
db.cosmosdb.containerstringDeprecated, use db.collection.name instead.mytableDeprecated
Replaced by db.collection.name.
db.cosmosdb.operation_typestringDeprecated, no replacement at this time.batch; create; deleteDeprecated
No replacement at this time.
db.cosmosdb.regions_contactedstring[]Deprecated, use azure.cosmosdb.operation.contacted_regions instead.["North Central US", "Australia East", "Australia Southeast"]Deprecated
Replaced by azure.cosmosdb.operation.contacted_regions.
db.cosmosdb.request_chargedoubleDeprecated, use azure.cosmosdb.operation.request_charge instead.46.18; 1.0Deprecated
Replaced by azure.cosmosdb.operation.request_charge.
db.cosmosdb.request_content_lengthintDeprecated, use azure.cosmosdb.request.body.size instead.Deprecated
Replaced by azure.cosmosdb.request.body.size.
db.cosmosdb.status_codeintDeprecated, use db.response.status_code instead.200; 201Deprecated
Replaced by db.response.status_code.
db.cosmosdb.sub_status_codeintDeprecated, use azure.cosmosdb.response.sub_status_code instead.1000; 1002Deprecated
Replaced by azure.cosmosdb.response.sub_status_code.
db.elasticsearch.cluster.namestringDeprecated, use db.namespace instead.e9106fc68e3044f0b1475b04bf4ffd5fDeprecated
Replaced by db.namespace.
db.elasticsearch.node.namestringDeprecated, use elasticsearch.node.name instead.instance-0000000001Deprecated
Replaced by elasticsearch.node.name.
db.elasticsearch.path_parts.<key>stringDeprecated, use db.operation.parameter instead.test-index; 123Deprecated
Replaced by db.operation.parameter.
db.instance.idstringDeprecated, no general replacement at this time. For Elasticsearch, use db.elasticsearch.node.name instead.mysql-e26b99z.example.comDeprecated
Deprecated, no general replacement at this time. For Elasticsearch, use db.elasticsearch.node.name instead.
db.jdbc.driver_classnamestringRemoved, no replacement at this time.org.postgresql.Driver; com.microsoft.sqlserver.jdbc.SQLServerDriverDeprecated
Removed as not used.
db.mongodb.collectionstringDeprecated, use db.collection.name instead.mytableDeprecated
Replaced by db.collection.name.
db.mssql.instance_namestringDeprecated, SQL Server instance is now populated as a part of db.namespace attribute.MSSQLSERVERDeprecated
Deprecated, no replacement at this time.
db.namestringDeprecated, use db.namespace instead.customers; mainDeprecated
Replaced by db.namespace.
db.operationstringDeprecated, use db.operation.name instead.findAndModify; HMSET; SELECTDeprecated
Replaced by db.operation.name.
db.redis.database_indexintDeprecated, use db.namespace instead.0; 1; 15Deprecated
Replaced by db.namespace.
db.sql.tablestringDeprecated, use db.collection.name instead, but only if not extracting the value from db.query.text.mytableDeprecated
Replaced by db.collection.name, but only if not extracting the value from db.query.text.
db.statementstringThe database statement being executed.SELECT * FROM wuser_table; SET mykey "WuValue"Deprecated
Replaced by db.query.text.
db.systemstringDeprecated, use db.system.name instead.other_sql; adabas; cacheDeprecated
Replaced by db.system.name.
db.userstringDeprecated, no replacement at this time.readonly_user; reporting_userDeprecated
No replacement at this time.

db.cassandra.consistency_level has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
allallDevelopment
anyanyDevelopment
each_quorumeach_quorumDevelopment
local_onelocal_oneDevelopment
local_quorumlocal_quorumDevelopment
local_seriallocal_serialDevelopment
oneoneDevelopment
quorumquorumDevelopment
serialserialDevelopment
threethreeDevelopment
twotwoDevelopment

db.cosmosdb.connection_mode has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
directDirect connection.Development
gatewayGateway (HTTP) connection.Development

db.cosmosdb.consistency_level has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
BoundedStalenessbounded_stalenessDevelopment
ConsistentPrefixconsistent_prefixDevelopment
EventualeventualDevelopment
SessionsessionDevelopment
StrongstrongDevelopment

db.cosmosdb.operation_type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
batchbatchDevelopment
createcreateDevelopment
deletedeleteDevelopment
executeexecuteDevelopment
execute_javascriptexecute_javascriptDevelopment
headheadDevelopment
head_feedhead_feedDevelopment
invalidinvalidDevelopment
patchpatchDevelopment
queryqueryDevelopment
query_planquery_planDevelopment
readreadDevelopment
read_feedread_feedDevelopment
replacereplaceDevelopment
upsertupsertDevelopment

db.system has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
adabasAdabas (Adaptable Database System)Development
cassandraApache CassandraDevelopment
clickhouseClickHouseDevelopment
cockroachdbCockroachDBDevelopment
cosmosdbMicrosoft Azure Cosmos DBDevelopment
couchbaseCouchbaseDevelopment
couchdbCouchDBDevelopment
db2IBM Db2Development
derbyApache DerbyDevelopment
dynamodbAmazon DynamoDBDevelopment
edbEnterpriseDBDevelopment
elasticsearchElasticsearchDevelopment
filemakerFileMakerDevelopment
firebirdFirebirdDevelopment
geodeApache GeodeDevelopment
h2H2Development
hanadbSAP HANADevelopment
hbaseApache HBaseDevelopment
hiveApache HiveDevelopment
hsqldbHyperSQL DataBaseDevelopment
influxdbInfluxDBDevelopment
informixInformixDevelopment
ingresIngresDevelopment
instantdbInstantDBDevelopment
interbaseInterBaseDevelopment
intersystems_cacheInterSystems CachéDevelopment
mariadbMariaDBDevelopment
maxdbSAP MaxDBDevelopment
memcachedMemcachedDevelopment
mongodbMongoDBDevelopment
mssqlMicrosoft SQL ServerDevelopment
mysqlMySQLDevelopment
neo4jNeo4jDevelopment
netezzaNetezzaDevelopment
opensearchOpenSearchDevelopment
oracleOracle DatabaseDevelopment
other_sqlSome other SQL database. Fallback only. See notes.Development
pervasivePervasive PSQLDevelopment
pointbasePointBaseDevelopment
postgresqlPostgreSQLDevelopment
progressProgress DatabaseDevelopment
redisRedisDevelopment
redshiftAmazon RedshiftDevelopment
spannerCloud SpannerDevelopment
sqliteSQLiteDevelopment
sybaseSybaseDevelopment
teradataTeradataDevelopment
trinoTrinoDevelopment
verticaVerticaDevelopment

Deprecated Database Metrics

“Describes deprecated db metrics attributes.”

AttributeTypeDescriptionExamplesStability
db.client.connections.pool.namestringDeprecated, use db.client.connection.pool.name instead.myDataSourceDeprecated
Replaced by db.client.connection.pool.name.
db.client.connections.statestringDeprecated, use db.client.connection.state instead.idleDeprecated
Replaced by db.client.connection.state.
pool.namestringDeprecated, use db.client.connection.pool.name instead.myDataSourceDeprecated
Replaced by db.client.connection.pool.name.
statestringDeprecated, use db.client.connection.state instead.idleDeprecated
Replaced by db.client.connection.state.

db.client.connections.state has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
idleidleDevelopment
usedusedDevelopment

state has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
idleidleDevelopment
usedusedDevelopment