120 lines
9.1 KiB
Markdown
120 lines
9.1 KiB
Markdown
<!--- Hugo front matter used to generate the website version of this page:
|
|
linkTitle: Redis
|
|
--->
|
|
|
|
# Semantic Conventions for Redis
|
|
|
|
**Status**: [Experimental][DocumentStatus]
|
|
|
|
The Semantic Conventions for [Redis](https://redis.com/) extend and override the [Database Semantic Conventions](database-spans.md).
|
|
|
|
`db.system` MUST be set to `"redis"` and SHOULD be provided **at span creation time**.
|
|
|
|
## Attributes
|
|
|
|
<!-- semconv db.redis -->
|
|
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
|
|
<!-- see templates/registry/markdown/snippet.md.j2 -->
|
|
<!-- prettier-ignore-start -->
|
|
<!-- markdownlint-capture -->
|
|
<!-- markdownlint-disable -->
|
|
|
|
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|
|
|---|---|---|---|---|---|
|
|
| [`db.namespace`](/docs/attributes-registry/db.md) | string | The [database index] associated with the connection, represented as a string. [1] | `0`; `1`; `15` | `Conditionally Required` If and only if it can be captured reliably. |  |
|
|
| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [2] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [3] |  |
|
|
| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | The Redis [simple error](https://redis.io/docs/latest/develop/reference/protocol-spec/#simple-errors) prefix. [4] | `ERR`; `WRONGTYPE`; `CLUSTERDOWN` | `Conditionally Required` [5] |  |
|
|
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [6] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. |  |
|
|
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Conditionally Required` [8] |  |
|
|
| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [9] | `2`; `3`; `4` | `Recommended` |  |
|
|
| [`db.query.text`](/docs/attributes-registry/db.md) | string | The full syntax of the Redis CLI command. [10] | `HMSET myhash field1 'Hello' field2 'World'` | `Recommended` [11] |  |
|
|
| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [12] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
|
| [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` if and only if `network.peer.address` is set. |  |
|
|
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [13] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
|
| [`db.query.parameter.<key>`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `<key>` being the parameter name, and the attribute value being a string representation of the parameter value. [14] | `someval`; `55` | `Opt-In` |  |
|
|
|
|
**[1]:** A connection's currently associated database index may change during its lifetime, e.g. from executing `SELECT <index>`.
|
|
|
|
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.
|
|
|
|
**[2]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
|
|
If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query.
|
|
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.
|
|
This attribute has stability level RELEASE CANDIDATE.
|
|
|
|
**[3]:** If readily available. The operation name MAY be parsed from the query text, in which case it SHOULD be the first operation name found in the query.
|
|
|
|
**[4]:** 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.
|
|
This attribute has stability level RELEASE CANDIDATE.
|
|
|
|
**[5]:** If the operation failed and status code is available.
|
|
|
|
**[6]:** 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]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
|
|
|
|
**[8]:** If using a port other than the default port for this DBMS and if `server.address` is set.
|
|
|
|
**[9]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
|
|
This attribute has stability level RELEASE CANDIDATE.
|
|
|
|
**[10]:** For **Redis**, 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/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`.
|
|
|
|
**[11]:** 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.
|
|
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.<key>`](../../docs/attributes-registry/db.md)).
|
|
|
|
**[12]:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
|
|
|
|
**[13]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
|
|
|
|
**[14]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders.
|
|
If a parameter has no name and instead is referenced only by index, then `<key>` SHOULD be the 0-based index.
|
|
This attribute has stability level RELEASE CANDIDATE.
|
|
|
|
|
|
|
|
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/attributes-registry/db.md)
|
|
* [`db.operation.name`](/docs/attributes-registry/db.md)
|
|
* [`db.query.text`](/docs/attributes-registry/db.md)
|
|
* [`server.address`](/docs/attributes-registry/server.md)
|
|
* [`server.port`](/docs/attributes-registry/server.md)
|
|
|
|
`error.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 |
|
|
|---|---|---|
|
|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
|
|
|
|
|
|
|
|
<!-- markdownlint-restore -->
|
|
<!-- prettier-ignore-end -->
|
|
<!-- END AUTOGENERATED TEXT -->
|
|
<!-- endsemconv -->
|
|
|
|
## 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 15"` |
|
|
| `db.system` | `"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]: https://opentelemetry.io/docs/specs/otel/document-status
|