> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/db/cassandra/ # Cassandraクライアント操作に関するセマンティック規約 **ステータス**: [Development][DocumentStatus] [Cassandra](https://cassandra.apache.org/)に関するセマンティック規約は、[データベースに関するセマンティック規約](/works/otel-specs-ja/semconv/db/)を拡張・オーバーライドします。 ## Spans **Status:** ![Development](https://img.shields.io/badge/-development-blue) Cassandraデータベースへの呼び出しを表すスパンは、[データベースクライアントのスパンに関する全般的なセマンティック規約](/works/otel-specs-ja/semconv/db/database-spans/)に従います。 `db.system.name` は `"cassandra"` に設定しなければならず（MUST）、**スパン作成時に**提供すべきです（SHOULD）。 **スパン名**は、全般的な[データベースのスパン名に関する規約](/works/otel-specs-ja/semconv/db/database-spans/#name)に従うべきです（SHOULD）。 **スパン種別**は `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.collection.name`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [1] | string | 操作の対象となるCassandraテーブルの名前。 [2] | `public.users`; `customers` | | [`db.namespace`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If available. | string | セッションに関連付けられたキースペース。 [3] | `mykeyspace` | | [`db.operation.name`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [4] | string | 実行されている操作またはコマンドの名前。 [5] | `findAndModify`; `HMSET`; `SELECT` | | [`db.response.status_code`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [6] | string | 文字列として表現された[Cassandraプロトコルのエラーコード](https://github.com/apache/cassandra/blob/cassandra-5.0/doc/native_protocol_v5.spec)。 [7] | `102`; `40020` | | [`error.type`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://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 | 操作が終了した際のエラーのクラスを記述する。 [8] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | | [`server.port`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [9] | int | サーバーのポート番号。 [10] | `80`; `8080`; `443` | | [`cassandra.consistency.level`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/cassandra/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | クエリの一貫性レベル。[CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html)の一貫性の値に基づく。 | `all`; `each_quorum`; `quorum` | | [`cassandra.coordinator.dc`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/cassandra/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | クエリのコーディネーターノードのデータセンター。 | `us-west-2` | | [`cassandra.coordinator.id`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/cassandra/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | クエリのコーディネーターノードのID。 | `be13faa2-8574-4d71-926d-27f16cf8a7af` | | [`cassandra.page.size`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/cassandra/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | ページングに使用されるフェッチサイズ。すなわち、一度に返される行数。 | `5000` | | [`cassandra.query.idempotent`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/cassandra/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | boolean | クエリが冪等であるかどうか。 | | | [`cassandra.speculative_execution.count`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/cassandra/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | クエリが投機的に実行された回数。クエリが投機的に実行されなかった場合は設定されないか、`0` になる。 | `0`; `2` | | [`db.operation.batch.size`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | バッチ操作に含まれるデータベース操作の数。 [11] | `2`; `3`; `4` | | [`db.query.summary`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` [12] | string | データベースクエリの低カーディナリティな要約。 [13] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | | [`db.query.text`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` [14] | string | 実行されているデータベースクエリ。 [15] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | | [`db.response.returned_rows`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | 操作によって返された行数。 [16] | `10`; `30`; `1000` | | [`network.peer.address`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | 操作が実行されたデータベースノードのピアアドレス。 [17] | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://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://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | データベースホストの名前。 [18] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`db.query.parameter.`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | データベースクエリのパラメータ。`` はパラメータ名であり、属性値はパラメータ値の文字列表現である。 [19] | `someval`; `55` | **[1] `db.collection.name`:** すぐに利用可能であり、かつデータベース呼び出しが単一のコレクションに対して実行される場合。 **[2] `db.collection.name`:** 値は、大文字小文字の正規化を試みずに、アプリケーションから提供されたとおりに取得することが推奨されます（RECOMMENDED）。 バッチ操作については、個々の操作が同じコレクション名を持つことがわかっている場合、そのコレクション名を使用すべきです（SHOULD）。 **[3] `db.namespace`:** データベースシステムが複数の名前空間コンポーネントを持つ場合、それらはコンポーネント間の区切り文字として `|` を使い、最も一般的なものから最も特定的なものへと連結すべきです（SHOULD）。欠落しているコンポーネント（およびそれに対応する区切り文字）は省略すべきです（SHOULD）。 個々のデータベースシステムに関するセマンティック規約は、そのシステムにおいて `db.namespace` が何を意味するかを文書化すべきです（SHOULD）。 値は、大文字小文字の正規化を試みずに、アプリケーションから提供されたとおりに取得することが推奨されます（RECOMMENDED）。 **[4] `db.operation.name`:** すぐに利用可能であり、かつデータベース呼び出しを記述する単一の操作名が存在する場合。 **[5] `db.operation.name`:** 値は、大文字小文字の正規化を試みずに、アプリケーションから提供されたとおりに取得することが推奨されます（RECOMMENDED）。 データベースシステムが非バッチ操作において複数の操作を含むクエリテキストをサポートする場合、操作名は `db.query.text` から抽出してはなりません（SHOULD NOT）。 操作名にスペースが含まれる可能性がある場合、連続する複数のスペースは単一のスペースに正規化すべきです（SHOULD）。 バッチ操作については、個々の操作が同じ操作名を持つことがわかっている場合、その操作名の前に `BATCH ` を付けて使用すべきです（SHOULD）。そうでない場合、`db.operation.name` は `BATCH`、またはより適切であれば他のデータベースシステム固有の用語にすべきです（SHOULD）。 **[6] `db.response.status_code`:** 操作が失敗し、ステータスコードが利用可能な場合。 **[7] `db.response.status_code`:** すべてのCassandraプロトコルエラーコードは、エラーとみなすべきです（SHOULD）。 **[8] `error.type`:** `error.type` は、データベースまたはクライアントライブラリによって返された `db.response.status_code`、または発生した例外の正式名称と一致すべきです（SHOULD）。 正式な例外型名を使用する場合、計装は最も関連性の高い型を報告するよう最善を尽くすべきです（SHOULD）。たとえば、元の例外が汎用的な例外にラップされている場合、元の例外を優先すべきです（SHOULD）。 計装は、`error.type` がどのように設定されるかを文書化すべきです（SHOULD）。 **[9] `server.port`:** このDBMSのデフォルトポート以外のポートを使用しており、かつ `server.address` が設定されている場合。 **[10] `server.port`:** クライアント側から観測され、かつ中間者を介して通信している場合、`server.port` は、利用可能であれば、あらゆる中間者（たとえばプロキシ）の背後にあるサーバーポートを表すべきです（SHOULD）。 **[11] `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）。 **[12] `db.query.summary`:** 計装フックを通じて利用可能な場合、または計装がクエリ要約の生成をサポートしている場合。 **[13] `db.query.summary`:** クエリ要約は、データベースクエリのクラスを記述するものであり、特に複雑なクエリを含むデータベース呼び出しのテレメトリーを分析する際に、グルーピングキーとして有用です。 要約は、計装フックその他の手段によって計装から利用可能な場合があります。利用可能でない場合、クエリ解析をサポートする計装は、[クエリ要約の生成](/works/otel-specs-ja/semconv/db/database-spans/#generating-a-summary-of-the-query)の節に従って要約を生成すべきです（SHOULD）。 バッチ操作については、個々の操作が同じクエリ要約を持つことがわかっている場合、そのクエリ要約の前に `BATCH ` を付けて使用すべきです（SHOULD）。そうでない場合、`db.query.summary` は `BATCH`、またはより適切であれば他のデータベースシステム固有の用語にすべきです（SHOULD）。 **[14] `db.query.text`:** 非パラメータ化クエリテキストは、機密データを除外するサニタイズ（たとえばクエリテキスト中のすべてのリテラル値をマスクするなど）が行われていない限り、デフォルトで収集すべきではありません（SHOULD NOT）。[`db.query.text` のサニタイズ](/works/otel-specs-ja/semconv/db/database-spans/#sanitization-of-dbquerytext)を参照してください。 パラメータ化クエリテキストはデフォルトで収集すべきです（SHOULD）（クエリパラメータの値自体はオプトインです。[`db.query.parameter.`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) を参照してください）。 **[15] `db.query.text`:** サニタイズについては[`db.query.text` のサニタイズ](/works/otel-specs-ja/semconv/db/database-spans/#sanitization-of-dbquerytext)を参照してください。 バッチ操作については、個々の操作が同じクエリテキストを持つことがわかっている場合、そのクエリテキストを使用すべきです（SHOULD）。そうでない場合、個々のクエリテキストはすべて、セパレーター `; `、またはより適切であれば他のデータベースシステム固有のセパレーターで連結すべきです（SHOULD）。 パラメータ化クエリテキストはサニタイズすべきではありません（SHOULD NOT）。パラメータ化クエリテキストには機密データが含まれる可能性がありますが、パラメータ化クエリを使用することで、ユーザーは機密データがパラメータ値として渡されるという強い意図を示していることになり、デフォルトでクエリテキストの静的な部分を取得することによるオブザーバビリティ上の利点が、そのリスクを上回ります。 **[16] `db.response.returned_rows`:** 計装がスパン終了時点で観測した、データベース操作によって返された行数。 **[17] `network.peer.address`:** データベース操作が複数のネットワーク呼び出し（たとえばリトライ）を伴う場合、最後に接続したノードのアドレスを使用すべきです（SHOULD）。 **[18] `server.address`:** クライアント側から観測され、かつ中間者を介して通信している場合、`server.address` は、利用可能であれば、あらゆる中間者の背後にあるサーバーアドレスを表すべきです（SHOULD）。 **[19] `db.query.parameter.`:** クエリパラメータに名前がなく、インデックスのみで参照される場合、`` は0始まりのインデックスにすべきです（SHOULD）。 `db.query.parameter.` は、`db.query.text` に存在するパラメータ化されたプレースホルダーと対応すべきです（SHOULD）。 値は、大文字小文字の正規化やサニタイズを試みずに、アプリケーションから提供されたとおりに取得することが推奨されます（RECOMMENDED）。 計装は、値にPIIや機密情報が含まれる可能性があるため、デフォルトで `db.query.parameter.` を取得すべきではありません（SHOULD NOT）。アプリケーションの運用者は、プライバシーやセキュリティ上の考慮に応じて特定のキーを有効化することが期待されます。 `db.query.parameter.` はバッチ操作では取得すべきではありません（SHOULD NOT）。 例: - パラメータ `"jdoe"` を持つクエリ `SELECT * FROM users where username = %s` では、属性 `db.query.parameter.0` を `"jdoe"` に設定すべきです（SHOULD）。 - パラメータ `userName = "jdoe"` を持つクエリ `"SELECT * FROM users WHERE username = %(userName)s;` では、属性 `db.query.parameter.userName` を `"jdoe"` に設定すべきです（SHOULD）。 以下の属性は、サンプリングの判断を行う上で重要な場合があり、**スパン作成時に**（提供する場合は）提供すべきです（SHOULD）。 * [`db.collection.name`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) * [`db.namespace`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) * [`db.operation.name`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) * [`db.query.summary`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) * [`db.query.text`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) * [`server.address`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) * [`server.port`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) --- `cassandra.consistency.level` には、以下の既知の値の一覧があります。これらのいずれかが該当する場合、対応する値を使用しなければなりません（MUST）。それ以外の場合は、独自の値を使用してもかまいません（MAY）。 | 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) | --- `error.type` には、以下の既知の値の一覧があります。これらのいずれかが該当する場合、対応する値を使用しなければなりません（MUST）。それ以外の場合は、独自の値を使用してもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | 計装が独自の値を定義していない場合に使用するフォールバックのエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ## Metrics Cassandraクライアントの計装は、全般的な[データベースクライアントのメトリクスに関するセマンティック規約](/works/otel-specs-ja/semconv/db/database-metrics/)に従ってメトリクスを収集すべきです（SHOULD）。 `db.system.name` は `"cassandra"` に設定しなければなりません（MUST）。 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status