Skip to content

db.md

Latest commit

 

History

History
363 lines (296 loc) · 35.7 KB

db.md

File metadata and controls

363 lines (296 loc) · 35.7 KB

DB

General Database Attributes

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

Attributes:

Key Stability Value Type Description Example Values
db.client.connection.pool.name Development 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 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. myDataSource
db.client.connection.state Development string The state of a connection in the pool idle
db.collection.name Stable string The name of a collection (table, container) within the database. [1] public.users; customers
db.namespace Stable string The name of the database, fully qualified within the server address and port. [2] customers; test.users
db.operation.batch.size Stable int The number of queries included in a batch operation. [3] 2; 3; 4
db.operation.name Stable string The name of the operation or command being executed. [4] findAndModify; HMSET; SELECT
db.operation.parameter.<key> Development string A database operation parameter, with <key> being the parameter name, and the attribute value being a string representation of the parameter value. [5] someval; 55
db.query.parameter.<key> Development string A database query parameter, with <key> being the parameter name, and the attribute value being a string representation of the parameter value. [6] someval; 55
db.query.summary Stable string Low cardinality summary of a database query. [7] SELECT wuser_table; INSERT shipping_details SELECT orders; get user by id
db.query.text Stable string The database query being executed. [8] SELECT * FROM wuser_table where username = ?; SET mykey ?
db.response.returned_rows Development int Number of rows returned by the operation. 10; 30; 1000
db.response.status_code Stable string Database response status code. [9] 102; ORA-17002; 08P01; 404
db.stored_procedure.name Stable string The name of a stored procedure within the database. [10] GetCustomer
db.system.name Stable string The database management system (DBMS) product as identified by the client instrumentation. [11] other_sql; softwareag.adabas; actian.ingres

[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.

It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.

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.

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

[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.

Value Description Stability
idle idle Development
used used Development

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.

Value Description Stability
actian.ingres Actian Ingres Development
aws.dynamodb Amazon DynamoDB Development
aws.redshift Amazon Redshift Development
azure.cosmosdb Azure Cosmos DB Development
cassandra Apache Cassandra Development
clickhouse ClickHouse Development
cockroachdb CockroachDB Development
couchbase Couchbase Development
couchdb Apache CouchDB Development
derby Apache Derby Development
elasticsearch Elasticsearch Development
firebirdsql Firebird Development
gcp.spanner Google Cloud Spanner Development
geode Apache Geode Development
h2database H2 Database Development
hbase Apache HBase Development
hive Apache Hive Development
hsqldb HyperSQL Database Development
ibm.db2 IBM Db2 Development
ibm.informix IBM Informix Development
ibm.netezza IBM Netezza Development
influxdb InfluxDB Development
instantdb Instant Development
intersystems.cache InterSystems Caché Development
mariadb MariaDB Stable
memcached Memcached Development
microsoft.sql_server Microsoft SQL Server Stable
mongodb MongoDB Development
mysql MySQL Stable
neo4j Neo4j Development
opensearch OpenSearch Development
oracle.db Oracle Database Development
other_sql Some other SQL database. Fallback only. Development
postgresql PostgreSQL Stable
redis Redis Development
sap.hana SAP HANA Development
sap.maxdb SAP MaxDB Development
softwareag.adabas Adabas (Adaptable Database System) Development
sqlite SQLite Development
teradata Teradata Development
trino Trino Development

Deprecated Database Attributes

Describes deprecated database attributes.

Attributes:

Key Stability Value Type Description Example Values
db.cassandra.consistency_level Deprecated
Replaced by cassandra.consistency.level.		 string Deprecated, use cassandra.consistency.level instead. all; each_quorum; quorum
db.cassandra.coordinator.dc Deprecated
Replaced by cassandra.coordinator.dc.		 string Deprecated, use cassandra.coordinator.dc instead. us-west-2
db.cassandra.coordinator.id Deprecated
Replaced by cassandra.coordinator.id.		 string Deprecated, use cassandra.coordinator.id instead. be13faa2-8574-4d71-926d-27f16cf8a7af
db.cassandra.idempotence Deprecated
Replaced by cassandra.query.idempotent.		 boolean Deprecated, use cassandra.query.idempotent instead.
db.cassandra.page_size Deprecated
Replaced by cassandra.page.size.		 int Deprecated, use cassandra.page.size instead. 5000
db.cassandra.speculative_execution_count Deprecated
Replaced by cassandra.speculative_execution.count.		 int Deprecated, use cassandra.speculative_execution.count instead. 0; 2
db.cassandra.table Deprecated
Replaced by db.collection.name.		 string Deprecated, use db.collection.name instead. mytable
db.connection_string Deprecated
Replaced by server.address and server.port.		 string Deprecated, use server.address, server.port attributes instead. Server=(localdb)\v11.0;Integrated Security=true;
db.cosmosdb.client_id Deprecated
Replaced by azure.client.id.		 string Deprecated, use azure.client.id instead. 3ba4827d-4422-483f-b59f-85b74211c11d
db.cosmosdb.connection_mode Deprecated
Replaced by azure.cosmosdb.connection.mode.		 string Deprecated, use azure.cosmosdb.connection.mode instead. gateway; direct
db.cosmosdb.consistency_level Deprecated
Replaced by azure.cosmosdb.consistency.level.		 string Deprecated, use cosmosdb.consistency.level instead. Eventual; ConsistentPrefix; BoundedStaleness; Strong; Session
db.cosmosdb.container Deprecated
Replaced by db.collection.name.		 string Deprecated, use db.collection.name instead. mytable
db.cosmosdb.operation_type Deprecated
Removed, no replacement at this time.		 string Deprecated, no replacement at this time. batch; create; delete
db.cosmosdb.regions_contacted Deprecated
Replaced by azure.cosmosdb.operation.contacted_regions.		 string[] Deprecated, use azure.cosmosdb.operation.contacted_regions instead. ["North Central US", "Australia East", "Australia Southeast"]
db.cosmosdb.request_charge Deprecated
Replaced by azure.cosmosdb.operation.request_charge.		 double Deprecated, use azure.cosmosdb.operation.request_charge instead. 46.18; 1.0
db.cosmosdb.request_content_length Deprecated
Replaced by azure.cosmosdb.request.body.size.		 int Deprecated, use azure.cosmosdb.request.body.size instead.
db.cosmosdb.status_code Deprecated
Use db.response.status_code instead.		 int Deprecated, use db.response.status_code instead. 200; 201
db.cosmosdb.sub_status_code Deprecated
Replaced by azure.cosmosdb.response.sub_status_code.		 int Deprecated, use azure.cosmosdb.response.sub_status_code instead. 1000; 1002
db.elasticsearch.cluster.name Deprecated
Replaced by db.namespace.		 string Deprecated, use db.namespace instead. e9106fc68e3044f0b1475b04bf4ffd5f
db.elasticsearch.node.name Deprecated
Replaced by elasticsearch.node.name.		 string Deprecated, use elasticsearch.node.name instead. instance-0000000001
db.elasticsearch.path_parts.<key> Deprecated
Replaced by db.operation.parameter.		 string Deprecated, use db.operation.parameter instead. test-index; 123
db.instance.id Deprecated
Removed, no general replacement at this time. For Elasticsearch, use db.elasticsearch.node.name instead.		 string Deprecated, no general replacement at this time. For Elasticsearch, use db.elasticsearch.node.name instead. mysql-e26b99z.example.com
db.jdbc.driver_classname Deprecated
Removed, no replacement at this time.		 string Removed, no replacement at this time. org.postgresql.Driver; com.microsoft.sqlserver.jdbc.SQLServerDriver
db.mongodb.collection Deprecated
Replaced by db.collection.name.		 string Deprecated, use db.collection.name instead. mytable
db.mssql.instance_name Deprecated
Removed, no replacement at this time.		 string Deprecated, SQL Server instance is now populated as a part of db.namespace attribute. MSSQLSERVER
db.name Deprecated
Replaced by db.namespace.		 string Deprecated, use db.namespace instead. customers; main
db.operation Deprecated
Replaced by db.operation.name.		 string Deprecated, use db.operation.name instead. findAndModify; HMSET; SELECT
db.redis.database_index Deprecated
Uncategorized.		 int Deprecated, use db.namespace instead. 0; 1; 15
db.sql.table Deprecated
Replaced by db.collection.name, but only if not extracting the value from db.query.text.		 string Deprecated, use db.collection.name instead. mytable
db.statement Deprecated
Replaced by db.query.text.		 string The database statement being executed. SELECT * FROM wuser_table; SET mykey "WuValue"
db.system Deprecated
Replaced by db.system.name.		 string Deprecated, use db.system.name instead. other_sql; adabas; intersystems_cache
db.user Deprecated
Removed, no replacement at this time.		 string Deprecated, no replacement at this time. readonly_user; reporting_user

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.

Value Description Stability
all all Development
any any Development
each_quorum each_quorum Development
local_one local_one Development
local_quorum local_quorum Development
local_serial local_serial Development
one one Development
quorum quorum Development
serial serial Development
three three Development
two two Development

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.

Value Description Stability
direct Direct connection. Development
gateway Gateway (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.

Value Description Stability
BoundedStaleness bounded_staleness Development
ConsistentPrefix consistent_prefix Development
Eventual eventual Development
Session session Development
Strong strong Development

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.

Value Description Stability
batch batch Development
create create Development
delete delete Development
execute execute Development
execute_javascript execute_javascript Development
head head Development
head_feed head_feed Development
invalid invalid Development
patch patch Development
query query Development
query_plan query_plan Development
read read Development
read_feed read_feed Development
replace replace Development
upsert upsert Development

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.

Value Description Stability
adabas Adabas (Adaptable Database System) Development
cassandra Apache Cassandra Development
clickhouse ClickHouse Development
cockroachdb CockroachDB Development
cosmosdb Microsoft Azure Cosmos DB Development
couchbase Couchbase Development
couchdb CouchDB Development
db2 IBM Db2 Development
derby Apache Derby Development
dynamodb Amazon DynamoDB Development
edb EnterpriseDB Development
elasticsearch Elasticsearch Development
filemaker FileMaker Development
firebird Firebird Development
geode Apache Geode Development
h2 H2 Development
hanadb SAP HANA Development
hbase Apache HBase Development
hive Apache Hive Development
hsqldb HyperSQL DataBase Development
influxdb InfluxDB Development
informix Informix Development
ingres Ingres Development
instantdb InstantDB Development
interbase InterBase Development
intersystems_cache InterSystems Caché Development
mariadb MariaDB Development
maxdb SAP MaxDB Development
memcached Memcached Development
mongodb MongoDB Development
mssql Microsoft SQL Server Development
mysql MySQL Development
neo4j Neo4j Development
netezza Netezza Development
opensearch OpenSearch Development
oracle Oracle Database Development
other_sql Some other SQL database. Fallback only. See notes. Development
pervasive Pervasive PSQL Development
pointbase PointBase Development
postgresql PostgreSQL Development
progress Progress Database Development
redis Redis Development
redshift Amazon Redshift Development
spanner Cloud Spanner Development
sqlite SQLite Development
sybase Sybase Development
teradata Teradata Development
trino Trino Development
vertica Vertica Development

Deprecated Database Metrics

Describes deprecated db metrics attributes.

Attributes:

Key Stability Value Type Description Example Values
db.client.connections.pool.name Deprecated
Replaced by db.client.connection.pool.name.		 string Deprecated, use db.client.connection.pool.name instead. myDataSource
db.client.connections.state Deprecated
Replaced by db.client.connection.state.		 string Deprecated, use db.client.connection.state instead. idle
pool.name Deprecated
Replaced by db.client.connection.pool.name.		 string Deprecated, use db.client.connection.pool.name instead. myDataSource
state Deprecated
Replaced by db.client.connection.state.		 string Deprecated, use db.client.connection.state instead. idle

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.

Value Description Stability
idle idle Development
used used Development

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.

Value Description Stability
idle idle Development
used used Development