Semantic conventions for database client spans

Status: Stable, Unless otherwise specified.

• Name
• Database server address
  • Database server endpoints
  • Service discovery
• Span definition
  • Notes and well-known identifiers for db.system.name
• Database client span duration
• Sanitization of db.query.text
• Generating a summary of the query
• Context propagation
  • SQL commenter
• Semantic conventions for specific database technologies

Name

Database spans MUST follow the overall guidelines for span names.

The span name SHOULD be {db.query.summary} if a summary is available.

If no summary is available, the span name SHOULD be {db.operation.name} {target} provided that a (low-cardinality) db.operation.name is available (see below for the exact definition of the {target} placeholder).

If a (low-cardinality) db.operation.name is not available, database span names SHOULD default to the {target}.

If neither {db.operation.name} nor {target} are available, span name SHOULD be {db.system.name}.

Semantic conventions for individual database systems MAY specify different span name format.

The {target} SHOULD describe the entity that the operation is performed against and SHOULD adhere to one of the following values, provided they are accessible:

• db.collection.name SHOULD be used for operations on a specific database collection.
• db.stored_procedure.name SHOULD be used for operations on a specific stored procedure.
• db.namespace SHOULD be used for operations on a specific database namespace.
• server.address SHOULD be used for operations without a specific collection, stored procedure, or namespace. If server.port is set, instrumentation SHOULD append it to server.address using : as the separator.

If a corresponding {target} value is not available for a specific operation, the instrumentation SHOULD omit the {target}. For example, for an operation describing SQL query on an anonymous table like SELECT * FROM (SELECT * FROM table) t, span name should be SELECT.

Database server address

Instrumentation SHOULD set server.address to the database address specified in the client configuration. It SHOULD NOT derive the value from the server selected for an operation. The value SHOULD remain unchanged when the client discovers or selects different database servers.

When the client connects through an intermediary, server.address SHOULD identify the configured database address behind the intermediary, if available.

Instrumentation SHOULD omit server.address if it cannot determine a safe, stable value from the client configuration.

Instrumentation SHOULD record the server contacted for an operation in network.peer.address and network.peer.port when available.

How instrumentation records server.address and server.port depends on whether the database client is configured with database server endpoints or uses service discovery.

Database server endpoints

When the client is configured with one or more database server endpoints, server.address SHOULD identify those endpoints. This includes seed and contact-point lists, even if the client later discovers additional topology from them.

A single endpoint SHOULD be a hostname, IP address, or UNIX socket path. Each endpoint in a list SHOULD be a hostname or IP address, optionally followed by a port. IPv6 addresses that include a port MUST be enclosed in square brackets. Multiple endpoints SHOULD be separated by commas without spaces. Instrumentation SHOULD NOT perform reverse DNS lookups for IP addresses.

Instrumentation SHOULD preserve endpoint order when it is significant, and otherwise SHOULD sort the endpoints lexicographically. Instrumentation MAY remove duplicate endpoints, but only when the duplicates carry no semantic meaning.

After applying endpoint ordering and any permitted deduplication, instrumentation SHOULD include at most the first five endpoints from the resulting list in server.address.

<endpoint>[,<endpoint>...]/<logical-target> MAY be used when all endpoints share a logical target that is an unambiguous single path segment.

Record port information for database server endpoints as follows:

• If all endpoints use the default port, ports SHOULD be omitted from server.address and server.port SHOULD NOT be set.
• If the client is configured with a single endpoint that uses a non-default port, the port SHOULD be omitted from server.address and SHOULD be recorded in server.port.
• If the client is configured with multiple endpoints and any endpoint uses a non-default port, each endpoint’s port SHOULD be included in server.address and server.port SHOULD NOT be set.

Examples:

Service discovery

For service discovery, server.address SHOULD contain the canonical, low-cardinality value from the client configuration. Depending on the client, this value identifies either a logical service or the discovery service used to obtain database server endpoints. Ports for configured discovery service endpoints SHOULD remain part of server.address. server.port SHOULD NOT be set.

Query and fragment components SHOULD be omitted unless they are part of the service identity.

Examples:

Span definition

Status:

This span describes database client call.

Instrumentations SHOULD, when possible, record database spans that represent the logical database operation as observed by the caller (such as client application).

When a database client provides higher-level convenience APIs for specific operations (e.g., calling a stored procedure), which internally generate and execute a generic query, it is RECOMMENDED to instrument the higher-level convenience APIs. These often allow setting db.operation.* attributes, which usually are not readily available at the generic query level.

Span name is covered in the Name section.

Span duration is covered in the Database client span duration section.

Span kind SHOULD be CLIENT. It MAY be set to INTERNAL on spans representing in-memory database calls. It’s RECOMMENDED to use CLIENT kind when database system being instrumented usually runs in a different process than its client or when database calls happen over instrumented protocol such as HTTP.

Span status SHOULD follow the Recording Errors document. Semantic conventions for individual systems SHOULD specify which values of db.response.status_code classify as errors.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
db.system.name		Required	string	The database management system (DBMS) product as identified by the client instrumentation. [1]	other_sql; softwareag.adabas; actian.ingres (see more)
db.collection.name		Conditionally Required [2]	string	The name of a collection (table, container) within the database. [3]	public.users; customers
db.namespace		Conditionally Required If available.	string	The name of the database, fully qualified within the server address and port. [4]	customers; test.users
db.operation.name		Conditionally Required [5]	string	The name of the operation or command being executed. [6]	findAndModify; HMSET; SELECT
db.response.status_code		Conditionally Required [7]	string	Database response status code. [8]	102; ORA-17002; 08P01; 404
error.type		Conditionally Required If and only if the operation failed.	string	Describes a class of error the operation ended with. [9]	timeout; java.net.UnknownHostException; server_certificate_invalid; 500
server.port		Conditionally Required [10]	int	Server port number. [11]	80; 8080; 443
db.operation.batch.size		Recommended	int	The number of database operations included in a batch operation. [12]	2; 3; 4
db.query.summary		Recommended [13]	string	Low cardinality summary of a database query. [14]	SELECT wuser_table; INSERT shipping_details SELECT orders; get user by id
db.query.text		Recommended [15]	string	The database query being executed. [16]	SELECT * FROM wuser_table where username = ?; SET mykey ?
db.stored_procedure.name		Recommended [17]	string	The name of a stored procedure within the database. [18]	GetCustomer
network.peer.address		Recommended If applicable for this database system.	string	Peer address of the database node where the operation was performed. [19]	10.1.2.80; /tmp/my.sock
network.peer.port		Recommended If and only if network.peer.address is set.	int	Peer port number of the network connection.	65123
server.address		Recommended	string	The database address specified in the client configuration. [20]	example.com; 10.1.2.80; /tmp/my.sock
db.query.parameter.<key>		Opt-In	string	A database query parameter, with <key> being the parameter name, and the attribute value being a string representation of the parameter value. [21]	someval; 55
db.response.returned_rows		Opt-In	int	Number of rows returned by the operation. [22]	10; 30; 1000

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

[2] db.collection.name: If readily available and if a database call is performed on a single collection.

[3] 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 would all have the same db.collection.name when executed as non-batch operations, then that collection name SHOULD be used.

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

[5] db.operation.name: If readily available and if there is a single operation name that describes the database call.

[6] 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 would all have the same db.operation.name when executed as non-batch operations, 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.

[7] db.response.status_code: If the operation failed and status code is available.

[8] 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. The value MAY use a standardized string representation of a numeric status code, if one exists, instead of the numeric code. The value MAY be a synthetic status provided by the client library rather than returned by the remote service. Semantic conventions for individual database systems SHOULD document what db.response.status_code means in the context of that system.

[9] error.type: The error.type SHOULD match the db.response.status_code returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. Instrumentations SHOULD document how error.type is populated.

[10] server.port: If server.address is set and the client is configured with a single database server endpoint that uses a non-default port.

[11] server.port: server.port SHOULD reflect the database port specified in the client configuration. It SHOULD NOT be derived from the server selected for an operation.

[12] db.operation.batch.size: Except for empty batch requests described below, a batch operation contains two or more database operations explicitly submitted as separate operations in a single client call, protocol message, or database command.

Requests to batch APIs that contain only one operation SHOULD be modeled as single operations, not as batch operations.

A database call is not a batch operation solely because one operation accepts multiple operands, such as keys, rows, documents, points, or other data elements, including Redis MGET with multiple keys.

In batch APIs that execute the same parameterized operation with parameter sets, each parameter set represents one database operation for determining whether the request is a batch operation. Requests with only one parameter set SHOULD be modeled as single operations, not as batch operations.

db.operation.batch.size SHOULD be set to the number of operations in the batch. It SHOULD NOT be set for non-batch operations.

A request to execute a batch operation with no operations SHOULD also be treated as a batch operation, and db.operation.batch.size SHOULD be set to 0.

[13] db.query.summary: if available through instrumentation hooks or if the instrumentation supports generating a query summary.

[14] 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 would all have the same db.query.summary when executed as non-batch operations, 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.

[15] db.query.text: Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See Sanitization of db.query.text. Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see db.query.parameter.<key>).

[16] db.query.text:

For sanitization see Sanitization of db.query.text. For batch operations, if the individual operations would all have the same db.query.text when executed as non-batch operations, 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.

[17] db.stored_procedure.name: If operation applies to a specific stored procedure.

[18] 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 would all have the same db.stored_procedure.name when executed as non-batch operations, then that stored procedure name SHOULD be used.

[19] network.peer.address: Semantic conventions for individual database systems SHOULD document whether network.peer.* attributes are applicable. Network peer address and port are useful when the application interacts with individual database nodes directly. If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.

[20] server.address: Instrumentation SHOULD set server.address to the database address specified in the client configuration. It SHOULD NOT derive the value from the server selected for an operation.

See Database server address for guidance and examples.

[21] 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 or sanitization.

Instrumentations SHOULD NOT capture db.query.parameter.<key> by default since values may contain PII or sensitive details. Application operators are expected to enable specific keys depending on their privacy and security considerations.

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

[22] db.response.returned_rows: The number of rows returned by the database operation as observed by the instrumentation at the time the span ends.

The following attributes can be important for making sampling decisions and SHOULD be provided at span creation time (if provided at all):

• db.collection.name
• db.namespace
• db.operation.name
• db.query.summary
• db.query.text
• db.system.name
• server.address
• server.port

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

Notes and well-known identifiers for db.system.name

The list above is a non-exhaustive list of well-known identifiers to be specified for db.system.name.

If a value defined in this list applies to the DBMS to which the request is sent, this value MUST be used. If no value defined in this list is suitable, a custom value MUST be provided. This custom value MUST be the name of the DBMS in lowercase and without a version number to stay consistent with existing identifiers.

It is encouraged to open a PR towards this specification to add missing values to the list, especially when instrumentations for those missing databases are written. This allows multiple instrumentations for the same database to be aligned and eases analyzing for backends.

The value other_sql is intended as a fallback and MUST only be used if the DBMS is known to be SQL-compliant but the concrete product is not known to the instrumentation. If the concrete DBMS is known to the instrumentation, its specific identifier MUST be used.

Backends could, for example, use the provided identifier to determine the appropriate SQL dialect for parsing the db.query.text.

When additional attributes are added that only apply to a specific DBMS, its identifier SHOULD be used as a namespace in the attribute key as for the attributes in the sections below.

Database client span duration

Database client spans SHOULD, when possible, cover the duration of the corresponding API call as observed by the caller (such as the client application). For example, if a transient issue happened and was retried within this database call, the corresponding span should cover the duration of the logical operation with all retries.

If there is any possibility for application code to not fully consume the database response (and for the database client library to then have to clean up the database response asynchronously), the database client span SHOULD NOT be ended in this cleanup phase, and instead SHOULD end at some point after the initial call returns to the caller. This avoids the span being ended asynchronously later on at a time which is no longer directly associated with the application code which made the database request.

Sanitization of db.query.text

The db.query.text SHOULD be collected by default only if there is sanitization that excludes sensitive information. Sanitization SHOULD replace all literals with a placeholder value. Such literals include, but are not limited to, String, Numeric, Date and Time, Boolean, Interval, Binary, and Hexadecimal literals. The placeholder value SHOULD be ?, unless it already has a defined meaning in the given database system, in which case the instrumentation MAY choose a different placeholder.

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.

IN-clauses MAY be collapsed during sanitization, e.g. from IN (?, ?, ?, ?) to IN (?), as this can help with extremely long IN-clauses, and can help control cardinality for users who choose to (optionally) add db.query.text to their metric attributes.

When performing sanitization, instrumentation MAY truncate the sanitized value for performance considerations (since sanitizing has a performance cost).

Generating a summary of the query

The db.query.summary attribute can be used to capture a shortened representation of the query. It SHOULD have low-cardinality and SHOULD NOT contain any dynamic or sensitive data.

Instrumentation SHOULD set the query summary if it is readily available through instrumentation hooks or other sources.

Otherwise:

• When instrumenting higher-level APIs that build queries internally - for example, those that create a table or execute a stored procedure - instrumentations SHOULD generate a db.query.summary from available operation(s) and target(s) using the format described in this section.

• When instrumenting APIs that operate at the query level, instrumentations that support query parsing SHOULD generate a query summary based on the db.query.text.

The summary SHOULD preserve the following parts of query in the order they were provided:

• operations such as SQL SELECT, INSERT, UPDATE, DELETE, and other commands
• operation targets such as collections, stored procedures, database names, etc

Instrumentations that support query parsing SHOULD parse the query and extract a list of operations and targets from the query. It SHOULD set db.query.summary attribute to the value formatted in the following way:

{operation1} {target1} {operation2} {target2} {target3} ...

Instrumentations SHOULD capture the values of operations and targets as provided by the application without attempting to do any case normalization. If the operation and target value is populated on db.operation.name, db.collection.name, or other attributes, it SHOULD match the value used in the db.query.summary.

Instrumentations that parse the query to set db.query.summary SHOULD truncate the summary to 255 characters (ensuring truncation does not occur within an operation name or target).

Examples:

• Query that consist of a single operation:

  SELECT *
  FROM   wuser_table
  WHERE  username = ?
  

  the corresponding db.query.summary is SELECT wuser_table.

• Query that performs multiple operations:

  INSERT INTO shipping_details
              (order_id,
              address)
  SELECT order_id,
         address
  FROM   orders
  WHERE  order_id = ?
  

  the corresponding db.query.summary is INSERT shipping_details SELECT orders.

• Query that performs an operation that’s applied to multiple collections:

  SELECT *
  FROM   songs,
         artists
  WHERE  songs.artist_id == artists.id
  

  the corresponding db.query.summary is SELECT songs artists.

• Query that performs an operation on an anonymous table:

  SELECT order_date
  FROM   (SELECT *
          FROM   orders o
                 JOIN customers c
                   ON o.customer_id = c.customer_id)
  

  the corresponding db.query.summary is SELECT SELECT orders customers.

• Query that performs an operation on multiple collections with double-quotes or other punctuation:

  SELECT *
  FROM   "song list",
         'artists'
  

  the corresponding db.query.summary is SELECT "song list" 'artists'.

• Stored procedure is executed using a convenience API such as one available in JDBC:

  connection.prepareCall("{call some_stored_procedure}");
  

  the corresponding db.query.summary is call some_stored_procedure, db.query.text is not populated. Note that CALL is the SQL standard keyword to invoke a stored procedure.

• Stored procedure is executed using Microsoft SQL Server driver’s convenience API Microsoft.Data.SqlClient:

  var command = new SqlCommand();
  command.CommandType = CommandType.StoredProcedure;
  command.CommandText = "some_stored_procedure";
  

  the corresponding db.query.summary is EXECUTE some_stored_procedure, db.query.text is not populated. Note that Microsoft SQL Server does not support the SQL Standard CALL keyword, but uses instead EXECUTE to invoke a stored procedure.

Semantic conventions for individual database systems or specialized instrumentations MAY specify a different db.query.summary format as long as produced summary remains relatively short and its cardinality remains low comparing to the db.query.text.

Context propagation

Status: Development

SQL commenter

Instrumentations MAY propagate context using SQL commenter by injecting comments into SQL queries before execution. SQL commenter-based context propagation SHOULD NOT be enabled by default, but instrumentation MAY allow users to opt into it.

The instrumentation implementation SHOULD append the comment to the end of the query. Semantic conventions for individual database systems MAY specify different format, which may include different position, encoding, or schema, depending on the specific database system’s requirements or preferences.

The instrumentation SHOULD allow users to pass a propagator to overwrite the global propagator. If no propagator is provided by the user, instrumentation SHOULD use the global propagator.

Examples:

• For a query SELECT * FROM songs with W3C TraceContext propagator:

  SELECT * FROM songs /*traceparent='00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',tracestate='congo%3Dt61rcWkgMzE%2Crojo%3D00f067aa0ba902b7'*/
  

  Note that adding high cardinality comments, like traceparent and tracestate, to queries can impact the performance for some database systems, such as:

  • Prepared statements in MySQL. See this related issue for more details.
  • Oracle and SQL Server for both prepared and non-prepared statements.

• For a query SELECT * FROM songs with a custom propagator that injects service.name into carrier where service.name is shoppingcart:

  SELECT * FROM songs /*service.name='shoppingcart'*/
  

Semantic conventions for specific database technologies

More specific Semantic Conventions are defined for the following database technologies:

• AWS DynamoDB: Semantic Conventions for AWS DynamoDB.
• Cassandra: Semantic Conventions for Cassandra.
• Azure Cosmos DB: Semantic Conventions for Azure Cosmos DB.
• CouchDB: Semantic Conventions for CouchDB.
• Elasticsearch: Semantic Conventions for Elasticsearch.
• HBase: Semantic Conventions for HBase.
• MongoDB: Semantic Conventions for MongoDB.
• Microsoft SQL Server: Semantic Conventions for Microsoft SQL Server.
• Redis: Semantic Conventions for Redis.
• SQL: Semantic Conventions for SQL databases.