# Semantic conventions for Cassandra client operations Site [llms.txt](/llms.txt) --- **Status**: [Development][DocumentStatus] - [Spans](#spans) - [Metrics](#metrics) The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend and override the [Database Semantic Conventions](README.md). ## Spans **Status:** ![Development](https://img.shields.io/badge/-development-blue) Spans representing calls to a Cassandra database adhere to the general [Semantic Conventions for Database Client Spans](/docs/specs/semconv/db/database-spans.md). **Span name** SHOULD follow the general [database span name convention](/docs/specs/semconv/db/database-spans.md#name) **Span kind** SHOULD be `CLIENT`. **Span status** SHOULD follow the [Recording Errors](/docs/specs/semconv/general/recording-errors.md) document. **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`db.system.name`](/docs/specs/semconv/registry/attributes/db.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `cassandra` | | [`db.collection.name`](/docs/specs/semconv/registry/attributes/db.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [2] | string | The name of the Cassandra table that the operation is acting upon. [3] | `public.users`; `customers` | | [`db.namespace`](/docs/specs/semconv/registry/attributes/db.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If available. | string | The keyspace associated with the session. [4] | `mykeyspace` | | [`db.operation.name`](/docs/specs/semconv/registry/attributes/db.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [5] | string | The name of the operation or command being executed. [6] | `findAndModify`; `HMSET`; `SELECT` | | [`db.response.status_code`](/docs/specs/semconv/registry/attributes/db.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [7] | string | [Cassandra protocol error code](https://github.com/apache/cassandra/blob/cassandra-5.0/doc/native_protocol_v5.spec) represented as a string. [8] | `102`; `40020` | | [`error.type`](/docs/specs/semconv/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `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`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [10] | int | Server port number. [11] | `80`; `8080`; `443` | | [`cassandra.consistency.level`](/docs/specs/semconv/registry/attributes/cassandra.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). | `all`; `each_quorum`; `quorum` [(see more)](#cassandra-consistency-level-values) | | [`cassandra.coordinator.dc`](/docs/specs/semconv/registry/attributes/cassandra.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The data center of the coordinating node for a query. | `us-west-2` | | [`cassandra.coordinator.id`](/docs/specs/semconv/registry/attributes/cassandra.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The ID of the coordinating node for a query. | `be13faa2-8574-4d71-926d-27f16cf8a7af` | | [`cassandra.page.size`](/docs/specs/semconv/registry/attributes/cassandra.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` | | [`cassandra.query.idempotent`](/docs/specs/semconv/registry/attributes/cassandra.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | boolean | Whether or not the query is idempotent. | | | [`cassandra.speculative_execution.count`](/docs/specs/semconv/registry/attributes/cassandra.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. | `0`; `2` | | [`db.operation.batch.size`](/docs/specs/semconv/registry/attributes/db.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | The number of database operations included in a batch operation. [12] | `2`; `3`; `4` | | [`db.query.summary`](/docs/specs/semconv/registry/attributes/db.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `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`](/docs/specs/semconv/registry/attributes/db.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` [15] | string | The database query being executed. [16] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | | [`db.response.returned_rows`](/docs/specs/semconv/registry/attributes/db.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | Number of rows returned by the operation. [17] | `10`; `30`; `1000` | | [`network.peer.address`](/docs/specs/semconv/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the database node where the operation was performed. [18] | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/specs/semconv/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If and only if `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | | [`server.address`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The database address specified in the client configuration. [19] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`db.query.parameter.`](/docs/specs/semconv/registry/attributes/db.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | A database query parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [20] | `someval`; `55` | **[1] `db.system.name`:** MUST be set to `"cassandra"`. **[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. 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`:** All Cassandra protocol error codes SHOULD be considered errors. **[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`](https://redis.io/docs/latest/commands/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](/docs/specs/semconv/db/database-spans.md#generating-a-summary-of-the-query) 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`](/docs/specs/semconv/db/database-spans.md#sanitization-of-dbquerytext). Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](/docs/specs/semconv/registry/attributes/db.md)). **[16] `db.query.text`:** > [!WARNING] > This attribute may contain large values. Applications should configure the OpenTelemetry SDK [attribute value limits](/docs/specs/otel/common/#attribute-limits). Instrumentations SHOULD additionally enforce an implementation-specific size limit before constructing or recording the value to avoid unbounded memory consumption. For sanitization see [Sanitization of `db.query.text`](/docs/specs/semconv/db/database-spans.md#sanitization-of-dbquerytext). 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.response.returned_rows`:** The number of rows returned by the database operation as observed by the instrumentation at the time the span ends. **[18] `network.peer.address`:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. **[19] `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. > [!WARNING] > > `server.address` MUST NOT contain credentials or other sensitive information. See [Database server address](/docs/specs/semconv/db/database-spans.md#database-server-address) for guidance and examples. **[20] `db.query.parameter.`:** If a query parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. `db.query.parameter.` 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.` 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.` 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"`. 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`](/docs/specs/semconv/registry/attributes/db.md) * [`db.namespace`](/docs/specs/semconv/registry/attributes/db.md) * [`db.operation.name`](/docs/specs/semconv/registry/attributes/db.md) * [`db.query.summary`](/docs/specs/semconv/registry/attributes/db.md) * [`db.query.text`](/docs/specs/semconv/registry/attributes/db.md) * [`db.system.name`](/docs/specs/semconv/registry/attributes/db.md) * [`server.address`](/docs/specs/semconv/registry/attributes/server.md) * [`server.port`](/docs/specs/semconv/registry/attributes/server.md) --- `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](https://img.shields.io/badge/-development-blue) | | `any` | Any | ![Development](https://img.shields.io/badge/-development-blue) | | `each_quorum` | Each Quorum | ![Development](https://img.shields.io/badge/-development-blue) | | `local_one` | Local One | ![Development](https://img.shields.io/badge/-development-blue) | | `local_quorum` | Local Quorum | ![Development](https://img.shields.io/badge/-development-blue) | | `local_serial` | Local Serial | ![Development](https://img.shields.io/badge/-development-blue) | | `one` | One | ![Development](https://img.shields.io/badge/-development-blue) | | `quorum` | Quorum | ![Development](https://img.shields.io/badge/-development-blue) | | `serial` | Serial | ![Development](https://img.shields.io/badge/-development-blue) | | `three` | Three | ![Development](https://img.shields.io/badge/-development-blue) | | `two` | Two | ![Development](https://img.shields.io/badge/-development-blue) | ## Metrics Cassandra client instrumentations SHOULD collect metrics according to the general [Semantic Conventions for Database Client Metrics](database-metrics.md). `db.system.name` MUST be set to `"cassandra"`. [DocumentStatus]: /docs/specs/otel/document-status/