> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/db/redis/ # Redisクライアントの操作に関するセマンティック規約 **ステータス**: [Development][DocumentStatus] [Redis](https://redis.com/)に関するセマンティック規約は、[データベースに関するセマンティック規約](/works/otel-specs-ja/semconv/db/database-spans/)を拡張・上書きします。 ## Spans **Status:** ![Development](https://img.shields.io/badge/-development-blue) Redisへの呼び出しを表すスパンは、[データベースクライアントのスパンに関する全般的なセマンティック規約](/works/otel-specs-ja/semconv/db/database-spans/)に準拠します。 `db.system.name` は `"redis"` に設定しなければならず（MUST）、**スパン作成時に**提供すべきです（SHOULD）。 **スパン名**は、[データベースのスパン名に関する全般的な命名規則](/works/otel-specs-ja/semconv/db/database-spans/#name)に従うべきです（SHOULD）。ただし、`db.namespace` は数値であり、スパン名の中で使うと分かりにくくなるため、スパン名には使用すべきではありません（SHOULD NOT）。 **スパン種別**は `CLIENT` にすべきです（SHOULD）。 **スパンステータス**は、[エラーの記録](/works/otel-specs-ja/semconv/general/recording-errors/)の文書に従うべきです（SHOULD）。 **Attributes:** | Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`db.operation.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | Redisのコマンド名。 [1] | `HMSET`; `GET`; `SET` | | [`db.namespace`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if it can be captured reliably. | string | 接続に関連付けられた[データベースインデックス](https://redis.io/docs/latest/commands/select/)。文字列として表現される。 [2] | `0`; `1`; `15` | | [`db.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [3] | string | Redisの[simple error](https://redis.io/docs/latest/develop/reference/protocol-spec/#simple-errors)のプレフィックス。 [4] | `ERR`; `WRONGTYPE`; `CLUSTERDOWN` | | [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | 操作が終了した際のエラーのクラスを記述する。 [5] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | | [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [6] | int | サーバーのポート番号。 [7] | `80`; `8080`; `443` | | [`db.operation.batch.size`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | バッチ操作に含まれるデータベース操作の数。 [8] | `2`; `3`; `4` | | [`db.query.text`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Redis CLIコマンドの完全な構文。 [9] | `HMSET myhash field1 ? field2 ?` | | [`db.stored_procedure.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If operation applies to a specific Lua script. | string | データベース内のLuaスクリプトの名前またはsha1ダイジェスト。 [10] | `GetCustomer` | | [`network.peer.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | 操作が実行されたデータベースノードのピアアドレス。 [11] | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` if and only if `network.peer.address` is set. | int | ネットワーク接続のピアポート番号。 | `65123` | | [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | データベースホストの名前。 [12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | **[1] `db.operation.name`:** 値は、大文字小文字の正規化を試みずに、アプリケーションから提供されたとおりに取得することが推奨されます（RECOMMENDED）。 [トランザクションとパイプライン呼び出し](https://redis.io/docs/latest/develop/clients/redis-py/transpipe/)については、個々の操作が同じコマンドを持つことがわかっている場合、そのコマンドの前に `MULTI ` または `PIPELINE ` を付けて使用すべきです（SHOULD）。そうでない場合、`db.operation.name` は `MULTI` または `PIPELINE` にすべきです（SHOULD）。 **[2] `db.namespace`:** 接続に現在関連付けられているデータベースインデックスは、たとえば `SELECT ` の実行によって、その生存期間中に変化することがあります。 計装が、追加のクエリの実行を引き起こさずに、各クエリで接続に現在関連付けられているデータベースインデックスを取得できない場合、接続確立時に提供されたデータベースインデックスにフォールバックして使用することが推奨されます（RECOMMENDED）。 計装は、`db.namespace` が接続確立時に提供されたデータベースインデックスを反映しているかどうかを文書化すべきです（SHOULD）。 **[3] `db.response.status_code`:** 操作が失敗し、ステータスコードが利用可能な場合。 **[4] `db.response.status_code`:** すべてのRedisのエラープレフィックスはエラーとして扱うべきです（SHOULD）。 **[5] `error.type`:** `error.type` は、データベースまたはクライアントライブラリによって返された `db.response.status_code`、または発生した例外の正式名称と一致すべきです（SHOULD）。 正式な例外型名を使用する場合、計装は最も関連性の高い型を報告するよう最善を尽くすべきです（SHOULD）。たとえば、元の例外が汎用的な例外にラップされている場合、元の例外を優先すべきです（SHOULD）。 計装は、`error.type` がどのように設定されるかを文書化すべきです（SHOULD）。 **[6] `server.port`:** このDBMSのデフォルトポート以外のポートを使用しており、かつ `server.address` が設定されている場合。 **[7] `server.port`:** クライアント側から観測され、かつ中間者を介して通信している場合、`server.port` は、利用可能であれば、あらゆる中間者（たとえばプロキシ）の背後にあるサーバーポートを表すべきです（SHOULD）。 **[8] `db.operation.batch.size`:** 以下に説明する空のバッチリクエストを除き、バッチ操作は、単一のクライアント呼び出し、プロトコルメッセージ、またはデータベースコマンドの中で、個別の操作として明示的に送信された2つ以上のデータベース操作を含みます。 1つの操作のみを含むバッチAPIへのリクエストは、バッチ操作としてではなく、単一の操作としてモデル化すべきです（SHOULD）。 1つの操作が複数のオペランド（キー、行、ドキュメント、点、その他のデータ要素など。複数のキーを持つRedisの[`MGET`](https://redis.io/docs/latest/commands/mget/)を含む）を受け付けるという理由だけでは、データベース呼び出しはバッチ操作にはなりません。 同じパラメータ化された操作をパラメータセットとともに実行するバッチAPIでは、各パラメータセットが、リクエストがバッチ操作であるかどうかを判定するための1つのデータベース操作を表します。パラメータセットが1つだけのリクエストは、バッチ操作としてではなく、単一の操作としてモデル化すべきです（SHOULD）。 `db.operation.batch.size` は、バッチ内の操作数に設定すべきです（SHOULD）。非バッチ操作に対しては設定すべきではありません（SHOULD NOT）。 操作を含まないバッチ操作を実行するリクエストもバッチ操作として扱うべきであり（SHOULD）、`db.operation.batch.size` は `0` に設定すべきです（SHOULD）。 **[9] `db.query.text`:** クエリテキストは、機密データを除外するサニタイズ（たとえばクエリテキスト中のすべてのリテラル値をマスクするなど）が行われていない限り、デフォルトで収集すべきではありません（SHOULD NOT）。 [`db.query.text` のサニタイズ](/works/otel-specs-ja/semconv/db/database-spans/#sanitization-of-dbquerytext)を参照してください。`db.query.text` に提供する値は、Redis CLIの構文に対応すべきです（SHOULD）。たとえば[`HMSET` コマンド](https://redis.io/docs/latest/commands/hmset)が呼び出された場合、`"HMSET myhash field1 ? field2 ?"` が `db.query.text` に適した値です。 **[10] `db.stored_procedure.name`:** [FCALL](https://redis.io/docs/latest/commands/fcall/) と [EVALSHA](https://redis.io/docs/latest/commands/evalsha/) を参照してください。 **[11] `network.peer.address`:** データベース操作が複数のネットワーク呼び出し（たとえばリトライ）を伴う場合、最後に接続したノードのアドレスを使用すべきです（SHOULD）。 **[12] `server.address`:** クライアント側から観測され、かつ中間者を介して通信している場合、`server.address` は、利用可能であれば、あらゆる中間者の背後にあるサーバーアドレスを表すべきです（SHOULD）。 以下の属性は、サンプリングの判断を行う上で重要な場合があり、**スパン作成時に**（提供する場合は）提供すべきです（SHOULD）。 * [`db.namespace`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) * [`db.operation.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) * [`db.query.text`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) * [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) * [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) --- `error.type` には、以下の既知の値の一覧があります。これらのいずれかが該当する場合、対応する値を使用しなければなりません（MUST）。それ以外の場合は、独自の値を使用してもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | 計装が独自の値を定義していない場合に使用するフォールバックのエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ## Example この例では、Redisにはユニックスドメインソケットで接続しているため、接続文字列は省略されています。 | 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]: https://opentelemetry.io/docs/specs/otel/document-status