# Semantic conventions for Redis client operations Site [llms.txt](/llms.txt) --- **Status**: [Development][DocumentStatus] The Semantic Conventions for [Redis](https://redis.com/) extend and override the [Database Semantic Conventions](database-spans.md). ## Spans **Status:** ![Development](https://img.shields.io/badge/-development-blue) Spans representing calls to Redis 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) except that `db.namespace` SHOULD NOT be used in the span name since it is a numeric value that ends up looking confusing. **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.operation.name`](/docs/specs/semconv/registry/attributes/db.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | The Redis command name. [1] | `HMSET`; `GET`; `SET` | | [`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. [2] | `redis` | | [`db.namespace`](/docs/specs/semconv/registry/attributes/db.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if it can be captured reliably. | string | The [database index] associated with the connection, represented as a string. [3] | `0`; `1`; `15` | | [`db.response.status_code`](/docs/specs/semconv/registry/attributes/db.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [4] | string | The Redis [simple error](https://redis.io/docs/latest/develop/reference/protocol-spec/#simple-errors) prefix. [5] | `ERR`; `WRONGTYPE`; `CLUSTERDOWN` | | [`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. [6] | `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` [7] | int | Server port number. [8] | `80`; `8080`; `443` | | [`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. [9] | `2`; `3`; `4` | | [`db.query.text`](/docs/specs/semconv/registry/attributes/db.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The full syntax of the Redis CLI command. [10] | `HMSET myhash field1 ? field2 ?` | | [`db.stored_procedure.name`](/docs/specs/semconv/registry/attributes/db.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If operation applies to a specific Lua script. | string | The name or sha1 digest of a Lua script in the database. [11] | `GetCustomer` | | [`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. [12] | `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. [13] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | **[1] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. For [transactions and pipelined calls](https://redis.io/docs/latest/develop/clients/redis-py/transpipe/), if the individual operations are known to have the same command then that command SHOULD be used prepended by `MULTI ` or `PIPELINE `. Otherwise `db.operation.name` SHOULD be `MULTI` or `PIPELINE`. **[2] `db.system.name`:** MUST be set to `"redis"`. **[3] `db.namespace`:** A connection's currently associated database index may change during its lifetime, e.g. from executing `SELECT `. If instrumentation is unable to capture the connection's currently associated database index on each query without triggering an additional query to be executed, then it is RECOMMENDED to fallback and use the database index provided when the connection was established. Instrumentation SHOULD document if `db.namespace` reflects the database index provided when the connection was established. **[4] `db.response.status_code`:** If the operation failed and status code is available. **[5] `db.response.status_code`:** All Redis error prefixes SHOULD be considered errors. **[6] `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. **[7] `server.port`:** If `server.address` is set and the client is configured with a single database server endpoint that uses a non-default port. **[8] `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. **[9] `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`. **[10] `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. 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). The value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/docs/latest/commands/hmset) is invoked, `"HMSET myhash field1 ? field2 ?"` would be a suitable value for `db.query.text`. **[11] `db.stored_procedure.name`:** See [FCALL](https://redis.io/docs/latest/commands/fcall/) and [EVALSHA](https://redis.io/docs/latest/commands/evalsha/). **[12] `network.peer.address`:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. **[13] `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. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`db.namespace`](/docs/specs/semconv/registry/attributes/db.md) * [`db.operation.name`](/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) ## Example In this example, Redis is connected using a UNIX domain socket and therefore the connection string is left out. | Key | Value | | :--------------------- | :-------------------------------------------- | | Span name | `"HMSET"` | | `db.system.name` | `"redis"` | | `network.peer.address` | `"/tmp/redis.sock"` | | `network.transport` | `"unix"` | | `db.namespace` | `"15"` | | `db.query.text` | `"HMSET myhash field1 'Hello' field2 'World"` | | `db.operation.name` | `"HMSET"` | [DocumentStatus]: /docs/specs/otel/document-status/