> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/db/database-spans/ # データベースクライアントのスパンに関するセマンティック規約 **ステータス**: 特に注記のない限り[Stable][DocumentStatus] > [!IMPORTANT] > > [この文書のv1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md) > 以前のバージョンを使っている既存のデータベース計装は、次に従うべきです。 > > * 既存のメジャーバージョンにおいて、デフォルトで発行するデータベース規約のバージョンを変更してはなりません（SHOULD NOT）。 > 規約には、属性、メトリクス名、スパン名、計測単位などが含まれますが、これらに限定されません。 > * 既存のメジャーバージョンにおいて、カテゴリー別の値をカンマ区切りで列挙するリストとして環境変数 `OTEL_SEMCONV_STABILITY_OPT_IN` を導入すべきです（SHOULD） > （例: http、databases、messaging）。値の一覧は次のとおりです。 > * `database` - 安定版のデータベース規約を発行し、それまで計装が発行していた実験的なデータベース規約の発行を停止します。 > * `database/dup` - 実験的な規約と安定版の規約の両方を発行し、安定版セマンティック規約への段階的な移行を可能にします。 > * これらの値がいずれも指定されていない場合のデフォルトの動作は、その計装がそれまで発行していた実験的なデータベース規約のバージョンをそのまま発行し続けることです。 > * 注記: 両方の値が指定されている場合、`database/dup` は `database` よりも優先されます。 > * 両方の規約セットを発行し始めてから少なくとも6か月間は、既存のメジャーバージョンを（少なくともセキュリティパッチの適用という形で）維持すべきです（SHOULD）。 > * 次のメジャーバージョンでは、この環境変数を削除し、安定版のデータベース規約のみを発行してもかまいません（MAY）。 ## Name データベースのスパンは、[スパン名に関する全般的なガイドライン](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.59.0/specification/trace/api.md#span)に従わなければなりません（MUST）。 **スパン名**は、要約が利用可能な場合は `{db.query.summary}` にすべきです（SHOULD）。 要約が利用可能でない場合、（低カーディナリティな）`db.operation.name` が利用可能であれば、スパン名は `{db.operation.name} {target}` にすべきです（SHOULD）。（[`{target}`](#target-placeholder)プレースホルダーの正確な定義は以下を参照してください。） （低カーディナリティな）`db.operation.name` が利用可能でない場合、データベースのスパン名はデフォルトで[`{target}`](#target-placeholder)にすべきです（SHOULD）。 `{db.operation.name}` と `{target}` のいずれも利用可能でない場合、スパン名は `{db.system.name}` にすべきです（SHOULD）。 個々のデータベースシステムに関するセマンティック規約は、異なるスパン名の形式を指定してもかまいません（MAY）。 `{target}`は、操作の対象となるエンティティを記述すべきであり（SHOULD）、アクセス可能であれば以下のいずれかの値に準拠すべきです（SHOULD）。 - 特定のデータベースコレクションに対する操作には `db.collection.name` を使用すべきです（SHOULD）。 - 特定のストアドプロシージャに対する操作には `db.stored_procedure.name` を使用すべきです（SHOULD）。 - 特定のデータベース名前空間に対する操作には `db.namespace` を使用すべきです（SHOULD）。 - 特定のコレクション、ストアドプロシージャ、名前空間を対象としないその他の操作には `server.address:server.port` を使用すべきです（SHOULD）。 特定の操作について対応する `{target}` の値が利用可能でない場合、計装は `{target}` を省略すべきです（SHOULD）。たとえば、`SELECT * FROM (SELECT * FROM table) t` のような無名テーブルに対するSQLクエリを記述する操作の場合、スパン名は `SELECT` にすべきです。 ## Span definition **Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) このスパンは、データベースクライアントの呼び出しを表します。 計装は、可能な場合、呼び出し元（クライアントアプリケーションなど）から観測される論理的なデータベース操作を表すデータベーススパンを記録すべきです（SHOULD）。 データベースクライアントが特定の操作（ストアドプロシージャの呼び出しなど）のための高レベルの便利なAPIを提供し、それが内部で汎用的なクエリを生成・実行する場合、その高レベルの便利なAPIを計装することが推奨されます（RECOMMENDED）。これらのAPIでは、汎用クエリのレベルでは通常取得できない `db.operation.*` 属性を設定できることが多いためです。 **スパン名**については、[Name](/works/otel-specs-ja/semconv/db/database-spans/#name)の節で説明しています。 **スパンの継続時間**については、[データベースクライアントのスパン継続時間](/works/otel-specs-ja/semconv/db/database-spans/#database-client-span-duration)の節で説明しています。 **スパン種別**は `CLIENT` にすべきです（SHOULD）。インメモリのデータベース呼び出しを表すスパンでは `INTERNAL` に設定してもかまいません（MAY）。 計装対象のデータベースシステムが、通常そのクライアントとは異なるプロセスで実行される場合や、HTTPのような計装されたプロトコルを介してデータベース呼び出しが行われる場合には、`CLIENT` 種別を使用することが推奨されます（RECOMMENDED）。 **スパンステータス**は、[エラーの記録](/works/otel-specs-ja/semconv/general/recording-errors/)の文書に従うべきです（SHOULD）。 個々のシステムに関するセマンティック規約は、`db.response.status_code` のどの値がエラーとして分類されるかを指定すべきです（SHOULD）。 **Attributes:** | Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`db.system.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | クライアント計装によって識別された、データベース管理システム（DBMS）製品。 [1] | `other_sql`; `softwareag.adabas`; `actian.ingres` | | [`db.collection.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [2] | string | データベース内のコレクション（テーブル、コンテナ）の名前。 [3] | `public.users`; `customers` | | [`db.namespace`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If available. | string | サーバーアドレスとポートの範囲内で完全修飾された、データベースの名前。 [4] | `customers`; `test.users` | | [`db.operation.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [5] | string | 実行されている操作またはコマンドの名前。 [6] | `findAndModify`; `HMSET`; `SELECT` | | [`db.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [7] | string | データベースの応答ステータスコード。 [8] | `102`; `ORA-17002`; `08P01`; `404` | | [`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 | 操作が終了した際のエラーのクラスを記述する。 [9] | `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` [10] | int | サーバーのポート番号。 [11] | `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 | バッチ操作に含まれるデータベース操作の数。 [12] | `2`; `3`; `4` | | [`db.query.summary`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` [13] | string | データベースクエリの低カーディナリティな要約。 [14] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | | [`db.query.text`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` [15] | string | 実行されているデータベースクエリ。 [16] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | | [`db.stored_procedure.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` [17] | string | データベース内のストアドプロシージャの名前。 [18] | `GetCustomer` | | [`network.peer.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If applicable for this database system. | string | 操作が実行されたデータベースノードのピアアドレス。 [19] | `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 | データベースホストの名前。 [20] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`db.query.parameter.`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | データベースクエリのパラメータ。`` はパラメータ名であり、属性値はパラメータ値の文字列表現である。 [21] | `someval`; `55` | | [`db.response.returned_rows`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | int | 操作によって返された行数。 [22] | `10`; `30`; `1000` | **[1] `db.system.name`:** 実際のDBMSは、クライアントによって識別されたものと異なる場合があります。たとえば、PostgreSQLクライアントライブラリを使用してCockroachDBに接続する場合、計装が把握できる最善の情報に基づき、`db.system.name` は `postgresql` に設定されます。 **[2] `db.collection.name`:** すぐに利用可能であり、かつデータベース呼び出しが単一のコレクションに対して実行される場合。 **[3] `db.collection.name`:** 値は、大文字小文字の正規化を試みずに、アプリケーションから提供されたとおりに取得することが推奨されます（RECOMMENDED）。 データベースシステムが非バッチ操作において複数のコレクションを含むクエリテキストをサポートする場合、コレクション名は `db.query.text` から抽出してはなりません（SHOULD NOT）。 バッチ操作については、個々の操作が同じコレクション名を持つことがわかっている場合、そのコレクション名を使用すべきです（SHOULD）。 **[4] `db.namespace`:** データベースシステムが複数の名前空間コンポーネントを持つ場合、それらはコンポーネント間の区切り文字として `|` を使い、最も一般的なものから最も特定的なものへと連結すべきです（SHOULD）。欠落しているコンポーネント（およびそれに対応する区切り文字）は省略すべきです（SHOULD）。 個々のデータベースシステムに関するセマンティック規約は、そのシステムにおいて `db.namespace` が何を意味するかを文書化すべきです（SHOULD）。 値は、大文字小文字の正規化を試みずに、アプリケーションから提供されたとおりに取得することが推奨されます（RECOMMENDED）。 **[5] `db.operation.name`:** すぐに利用可能であり、かつデータベース呼び出しを記述する単一の操作名が存在する場合。 **[6] `db.operation.name`:** 値は、大文字小文字の正規化を試みずに、アプリケーションから提供されたとおりに取得することが推奨されます（RECOMMENDED）。 データベースシステムが非バッチ操作において複数の操作を含むクエリテキストをサポートする場合、操作名は `db.query.text` から抽出してはなりません（SHOULD NOT）。 操作名にスペースが含まれる可能性がある場合、連続する複数のスペースは単一のスペースに正規化すべきです（SHOULD）。 バッチ操作については、個々の操作が同じ操作名を持つことがわかっている場合、その操作名の前に `BATCH ` を付けて使用すべきです（SHOULD）。そうでない場合、`db.operation.name` は `BATCH`、またはより適切であれば他のデータベースシステム固有の用語にすべきです（SHOULD）。 **[7] `db.response.status_code`:** 操作が失敗し、ステータスコードが利用可能な場合。 **[8] `db.response.status_code`:** データベースによって返されたステータスコード。通常はエラーコードを表しますが、部分的な成功、警告、または様々な種類の成功結果の区別を表すこともあります。 個々のデータベースシステムに関するセマンティック規約は、そのシステムにおいて `db.response.status_code` が何を意味するかを文書化すべきです（SHOULD）。 **[9] `error.type`:** `error.type` は、データベースまたはクライアントライブラリによって返された `db.response.status_code`、または発生した例外の正式名称と一致すべきです（SHOULD）。 正式な例外型名を使用する場合、計装は最も関連性の高い型を報告するよう最善を尽くすべきです（SHOULD）。たとえば、元の例外が汎用的な例外にラップされている場合、元の例外を優先すべきです（SHOULD）。 計装は、`error.type` がどのように設定されるかを文書化すべきです（SHOULD）。 **[10] `server.port`:** このDBMSのデフォルトポート以外のポートを使用しており、かつ `server.address` が設定されている場合。 **[11] `server.port`:** クライアント側から観測され、かつ中間者を介して通信している場合、`server.port` は、利用可能であれば、あらゆる中間者（たとえばプロキシ）の背後にあるサーバーポートを表すべきです（SHOULD）。 **[12] `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）。 **[13] `db.query.summary`:** 計装フックを通じて利用可能な場合、または計装がクエリ要約の生成をサポートしている場合。 **[14] `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）。 **[15] `db.query.text`:** 非パラメータ化クエリテキストは、機密データを除外するサニタイズ（たとえばクエリテキスト中のすべてのリテラル値をマスクするなど）が行われていない限り、デフォルトで収集すべきではありません（SHOULD NOT）。[`db.query.text` のサニタイズ](/works/otel-specs-ja/semconv/db/database-spans/#sanitization-of-dbquerytext)を参照してください。 パラメータ化クエリテキストはデフォルトで収集すべきです（SHOULD）（クエリパラメータの値自体はオプトインです。[`db.query.parameter.`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) を参照してください）。 **[16] `db.query.text`:** サニタイズについては[`db.query.text` のサニタイズ](/works/otel-specs-ja/semconv/db/database-spans/#sanitization-of-dbquerytext)を参照してください。 バッチ操作については、個々の操作が同じクエリテキストを持つことがわかっている場合、そのクエリテキストを使用すべきです（SHOULD）。そうでない場合、個々のクエリテキストはすべて、セパレーター `; `、またはより適切であれば他のデータベースシステム固有のセパレーターで連結すべきです（SHOULD）。 パラメータ化クエリテキストはサニタイズすべきではありません（SHOULD NOT）。パラメータ化クエリテキストには機密データが含まれる可能性がありますが、パラメータ化クエリを使用することで、ユーザーは機密データがパラメータ値として渡されるという強い意図を示していることになり、デフォルトでクエリテキストの静的な部分を取得することによるオブザーバビリティ上の利点が、そのリスクを上回ります。 **[17] `db.stored_procedure.name`:** 操作が特定のストアドプロシージャに適用される場合。 **[18] `db.stored_procedure.name`:** 値は、大文字小文字の正規化を試みずに、アプリケーションから提供されたとおりに取得することが推奨されます（RECOMMENDED）。 バッチ操作については、個々の操作が同じストアドプロシージャ名を持つことがわかっている場合、そのストアドプロシージャ名を使用すべきです（SHOULD）。 **[19] `network.peer.address`:** 個々のデータベースシステムに関するセマンティック規約は、`network.peer.*` 属性が適用可能かどうかを文書化すべきです（SHOULD）。ネットワークピアのアドレスとポートは、アプリケーションが個々のデータベースノードと直接やり取りする場合に有用です。 データベース操作が複数のネットワーク呼び出し（たとえばリトライ）を伴う場合、最後に接続したノードのアドレスを使用すべきです（SHOULD）。 **[20] `server.address`:** クライアント側から観測され、かつ中間者を介して通信している場合、`server.address` は、利用可能であれば、あらゆる中間者の背後にあるサーバーアドレスを表すべきです（SHOULD）。 **[21] `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）。 **[22] `db.response.returned_rows`:** 計装がスパン終了時点で観測した、データベース操作によって返された行数。 以下の属性は、サンプリングの判断を行う上で重要な場合があり、**スパン作成時に**（提供する場合は）提供すべきです（SHOULD）。 * [`db.collection.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) * [`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.summary`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) * [`db.query.text`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) * [`db.system.name`](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/) --- `db.system.name` には、以下の既知の値の一覧があります。これらのいずれかが該当する場合、対応する値を使用しなければなりません（MUST）。それ以外の場合は、独自の値を使用してもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `actian.ingres` | [Actian Ingres](https://www.actian.com/databases/ingres/) | ![Development](https://img.shields.io/badge/-development-blue) | | `aws.dynamodb` | [Amazon DynamoDB](https://aws.amazon.com/pm/dynamodb/) | ![Development](https://img.shields.io/badge/-development-blue) | | `aws.redshift` | [Amazon Redshift](https://aws.amazon.com/redshift/) | ![Development](https://img.shields.io/badge/-development-blue) | | `azure.cosmosdb` | [Azure Cosmos DB](https://learn.microsoft.com/azure/cosmos-db) | ![Development](https://img.shields.io/badge/-development-blue) | | `cassandra` | [Apache Cassandra](https://cassandra.apache.org/) | ![Development](https://img.shields.io/badge/-development-blue) | | `clickhouse` | [ClickHouse](https://clickhouse.com/) | ![Development](https://img.shields.io/badge/-development-blue) | | `cockroachdb` | [CockroachDB](https://www.cockroachlabs.com/) | ![Development](https://img.shields.io/badge/-development-blue) | | `couchbase` | [Couchbase](https://www.couchbase.com/) | ![Development](https://img.shields.io/badge/-development-blue) | | `couchdb` | [Apache CouchDB](https://couchdb.apache.org/) | ![Development](https://img.shields.io/badge/-development-blue) | | `derby` | [Apache Derby](https://db.apache.org/derby/) | ![Development](https://img.shields.io/badge/-development-blue) | | `elasticsearch` | [Elasticsearch](https://www.elastic.co/elasticsearch) | ![Development](https://img.shields.io/badge/-development-blue) | | `firebirdsql` | [Firebird](https://www.firebirdsql.org/) | ![Development](https://img.shields.io/badge/-development-blue) | | `gcp.spanner` | [Google Cloud Spanner](https://cloud.google.com/spanner) | ![Development](https://img.shields.io/badge/-development-blue) | | `geode` | [Apache Geode](https://geode.apache.org/) | ![Development](https://img.shields.io/badge/-development-blue) | | `h2database` | [H2 Database](https://h2database.com/) | ![Development](https://img.shields.io/badge/-development-blue) | | `hbase` | [Apache HBase](https://hbase.apache.org/) | ![Development](https://img.shields.io/badge/-development-blue) | | `hive` | [Apache Hive](https://hive.apache.org/) | ![Development](https://img.shields.io/badge/-development-blue) | | `hsqldb` | [HyperSQL Database](https://hsqldb.org/) | ![Development](https://img.shields.io/badge/-development-blue) | | `ibm.db2` | [IBM Db2](https://www.ibm.com/db2) | ![Development](https://img.shields.io/badge/-development-blue) | | `ibm.informix` | [IBM Informix](https://www.ibm.com/products/informix) | ![Development](https://img.shields.io/badge/-development-blue) | | `ibm.netezza` | [IBM Netezza](https://www.ibm.com/products/netezza) | ![Development](https://img.shields.io/badge/-development-blue) | | `influxdb` | [InfluxDB](https://www.influxdata.com/) | ![Development](https://img.shields.io/badge/-development-blue) | | `instantdb` | [Instant](https://www.instantdb.com/) | ![Development](https://img.shields.io/badge/-development-blue) | | `intersystems.cache` | [InterSystems Caché](https://www.intersystems.com/products/cache/) | ![Development](https://img.shields.io/badge/-development-blue) | | `mariadb` | [MariaDB](https://mariadb.org/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `memcached` | [Memcached](https://memcached.org/) | ![Development](https://img.shields.io/badge/-development-blue) | | `microsoft.sql_server` | [Microsoft SQL Server](https://www.microsoft.com/sql-server) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `mongodb` | [MongoDB](https://www.mongodb.com/) | ![Development](https://img.shields.io/badge/-development-blue) | | `mysql` | [MySQL](https://www.mysql.com/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `neo4j` | [Neo4j](https://neo4j.com/) | ![Development](https://img.shields.io/badge/-development-blue) | | `opensearch` | [OpenSearch](https://opensearch.org/) | ![Development](https://img.shields.io/badge/-development-blue) | | `oracle.db` | [Oracle Database](https://www.oracle.com/database/) | ![Development](https://img.shields.io/badge/-development-blue) | | `other_sql` | その他のSQLデータベース。フォールバックとしてのみ使用する。 | ![Development](https://img.shields.io/badge/-development-blue) | | `postgresql` | [PostgreSQL](https://www.postgresql.org/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `redis` | [Redis](https://redis.io/) | ![Development](https://img.shields.io/badge/-development-blue) | | `sap.hana` | [SAP HANA](https://www.sap.com/products/technology-platform/hana/what-is-sap-hana.html) | ![Development](https://img.shields.io/badge/-development-blue) | | `sap.maxdb` | [SAP MaxDB](https://maxdb.sap.com/) | ![Development](https://img.shields.io/badge/-development-blue) | | `softwareag.adabas` | [Adabas (Adaptable Database System)](https://documentation.softwareag.com/?pf=adabas) | ![Development](https://img.shields.io/badge/-development-blue) | | `sqlite` | [SQLite](https://www.sqlite.org/) | ![Development](https://img.shields.io/badge/-development-blue) | | `teradata` | [Teradata](https://www.teradata.com/) | ![Development](https://img.shields.io/badge/-development-blue) | | `trino` | [Trino](https://trino.io/) | ![Development](https://img.shields.io/badge/-development-blue) | --- `error.type` には、以下の既知の値の一覧があります。これらのいずれかが該当する場合、対応する値を使用しなければなりません（MUST）。それ以外の場合は、独自の値を使用してもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | 計装が独自の値を定義していない場合に使用するフォールバックのエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ### Notes and well-known identifiers for `db.system.name` 上記の一覧は、`db.system.name` に指定すべき既知の識別子の非網羅的なリストです。 このリストで定義されている値がリクエスト先のDBMSに該当する場合、その値を使用しなければなりません（MUST）。 このリストで定義されている適切な値がない場合、独自の値を提供しなければなりません（MUST）。 既存の識別子との整合性を保つため、この独自の値はDBMSの名前を小文字で表記し、バージョン番号を含まないものでなければなりません（MUST）。 不足している値を追加するためこの仕様書にPRを開くことが推奨されます。特に、それらの不足しているデータベース向けの計装が書かれる際にはそうすべきです。これにより、同じデータベースに対する複数の計装を整合させることができ、バックエンドでの分析が容易になります。 `other_sql` はフォールバックとして意図されており、DBMSがSQL準拠であることが判明しているが具体的な製品が計装にとって不明な場合にのみ使用しなければなりません（MUST）。 具体的なDBMSが計装にとって既知である場合は、その特定の識別子を使用しなければなりません（MUST）。 たとえば、バックエンドは提供された識別子を使って、`db.query.text` を解析するための適切なSQLダイアレクトを判定できます。 特定のDBMSにのみ適用される追加の属性が追加される場合、以下の節にある属性と同様に、その識別子を属性キーの名前空間として使用すべきです（SHOULD）。 ## Database client span duration データベースクライアントのスパンは、可能な場合、呼び出し元（クライアントアプリケーションなど）から観測される対応するAPI呼び出しの継続時間をカバーすべきです（SHOULD）。 たとえば、このデータベース呼び出しの中で一時的な問題が発生してリトライされた場合、対応するスパンはすべてのリトライを含む論理的な操作の継続時間をカバーすべきです。 アプリケーションコードがデータベースの応答を完全に消費しない可能性がある場合（そのためデータベースクライアントライブラリが後で非同期にデータベースの応答をクリーンアップする必要がある場合）、データベースクライアントのスパンはこのクリーンアップの段階で終了すべきではなく（SHOULD NOT）、代わりに最初の呼び出しが呼び出し元に戻った後のある時点で終了すべきです（SHOULD）。 これにより、スパンが、リクエストを行ったアプリケーションコードともはや直接関連付けられない時点で、後から非同期に終了してしまうことを避けられます。 ## Sanitization of `db.query.text` `db.query.text` は、機密情報を除外するサニタイズが行われている場合にのみ、デフォルトで収集すべきです（SHOULD）。 サニタイズは、すべてのリテラルをプレースホルダーの値に置き換えるべきです（SHOULD）。 そのようなリテラルには、文字列、数値、日付・時刻、真偽値、インターバル、バイナリ、16進数のリテラルが含まれますが、これらに限られません。 プレースホルダーの値は、対象のデータベースシステムにおいて既に定義された意味を持っていない限り `?` にすべきです（SHOULD）。定義された意味を持つ場合、計装は異なるプレースホルダーを選択してもかまいません（MAY）。 パラメータ化クエリテキストはサニタイズすべきではありません（SHOULD NOT）。 パラメータ化クエリテキストには機密データが含まれる可能性がありますが、パラメータ化クエリを使用することで、ユーザーは機密データがパラメータ値として渡されるという強い意図を示していることになり、デフォルトでクエリテキストの静的な部分を取得することによるオブザーバビリティ上の利点が、そのリスクを上回ります。 [IN句](https://wikipedia.org/wiki/SQL_syntax#Operators)は、サニタイズの際に折りたたんでもかまいません（MAY）。たとえば `IN (?, ?, ?, ?)` を `IN (?)` にするなどです。これは非常に長いIN句に対して有効であり、（オプションで）`db.query.text` をメトリクス属性に追加することを選んだユーザーのために、カーディナリティを制御する助けになります。 サニタイズを実行する際、計装はパフォーマンス上の理由から（サニタイズにはパフォーマンス上のコストがあるため）サニタイズ済みの値を切り詰めてもかまいません（MAY）。 ## Generating a summary of the query `db.query.summary` 属性は、クエリの短縮された表現を取得するために使用できます。この属性は低カーディナリティであるべきであり（SHOULD）、動的または機密性のあるデータを含むべきではありません（SHOULD NOT）。 > [!NOTE] > > `db.query.text` 属性は、個々のクエリを識別することを目的としています。デフォルトで取得される際にサニタイズされているとしても、依然として高いカーディナリティを持つ可能性があり、数百行に達することもあります。 > > `db.query.summary` は、一般的な場合にスパン名やメトリクス属性として使用できる、より粒度の粗いグルーピングキーを提供することを目的としています。この属性には、クエリ、データベース、またはアプリケーションのパフォーマンスに大きな影響を与える情報のみを含めるべきです（SHOULD）。 計装は、計装フックその他の手段によってクエリ要約がすぐに利用可能な場合、クエリ要約を設定すべきです（SHOULD）。 そうでない場合は、次のようにします。 - 内部でクエリを構築する高レベルのAPI（テーブルを作成したりストアドプロシージャを実行したりするAPIなど）を計装する場合、計装はこの節で説明する形式を使って、利用可能な操作と対象から `db.query.summary` を生成すべきです（SHOULD）。 - クエリレベルで動作するAPIを計装する場合、クエリ解析をサポートする計装は、`db.query.text` に基づいてクエリ要約を生成すべきです（SHOULD）。 要約は、提供された順序で、クエリの以下の部分を保持すべきです（SHOULD）。 - SQLのSELECT、INSERT、UPDATE、DELETEなどのコマンドといった操作 - コレクション、ストアドプロシージャ、データベース名などの操作対象 クエリ解析をサポートする計装は、クエリを解析して操作と対象のリストを抽出すべきです（SHOULD）。`db.query.summary` 属性には、次のように整形された値を設定すべきです（SHOULD）。 ``` {operation1} {target1} {operation2} {target2} {target3} ... ``` 計装は、大文字小文字の正規化を試みずに、アプリケーションから提供されたとおりに操作と対象の値を取得すべきです（SHOULD）。操作と対象の値が `db.operation.name`、`db.collection.name`、その他の属性に設定されている場合、`db.query.summary` で使用されている値と一致すべきです（SHOULD）。 クエリを解析して `db.query.summary` を設定する計装は、要約を255文字に切り詰めるべきです（SHOULD）（切り詰めが操作名や対象の途中で発生しないようにします）。 **例**: - 単一の操作からなるクエリ: ```sql SELECT * FROM wuser_table WHERE username = ? ``` 対応する `db.query.summary` は `SELECT wuser_table` です。 - 複数の操作を実行するクエリ: ```sql INSERT INTO shipping_details (order_id, address) SELECT order_id, address FROM orders WHERE order_id = ? ``` 対応する `db.query.summary` は `INSERT shipping_details SELECT orders` です。 - 複数のコレクションに適用される操作を実行するクエリ: ```sql SELECT * FROM songs, artists WHERE songs.artist_id == artists.id ``` 対応する `db.query.summary` は `SELECT songs artists` です。 - 無名テーブルに対して操作を実行するクエリ: ```sql SELECT order_date FROM (SELECT * FROM orders o JOIN customers c ON o.customer_id = c.customer_id) ``` 対応する `db.query.summary` は `SELECT SELECT orders customers` です。 - 二重引用符やその他の句読点を伴う複数のコレクションに対して操作を実行するクエリ: ```sql SELECT * FROM "song list", 'artists' ``` 対応する `db.query.summary` は `SELECT "song list" 'artists'` です。 - [JDBC](https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html#prepareCall-java.lang.String-)のような便利なAPIを使ってストアドプロシージャが実行される場合: ```java connection.prepareCall("{call some_stored_procedure}"); ``` 対応する `db.query.summary` は `call some_stored_procedure` であり、`db.query.text` は設定されません。`CALL` はストアドプロシージャを呼び出すためのSQL標準のキーワードであることに注意してください。 - Microsoft SQL Serverドライバの便利なAPIである [Microsoft.Data.SqlClient](https://learn.microsoft.com/dotnet/api/microsoft.data.sqlclient.sqlcommand.commandtype)を使ってストアドプロシージャが実行される場合: ```csharp var command = new SqlCommand(); command.CommandType = CommandType.StoredProcedure; command.CommandText = "some_stored_procedure"; ``` 対応する `db.query.summary` は `EXECUTE some_stored_procedure` であり、`db.query.text` は設定されません。Microsoft SQL ServerはSQL標準の `CALL` キーワードをサポートしておらず、代わりにストアドプロシージャを呼び出すために `EXECUTE` を使用することに注意してください。 個々のデータベースシステムまたは特化した計装に関するセマンティック規約は、生成される要約が比較的短く保たれ、`db.query.text` と比較してそのカーディナリティが低く保たれる限り、異なる `db.query.summary` の形式を指定してもかまいません（MAY）。 ## Context propagation **ステータス**: [Development][DocumentStatus] ### SQL commenter 計装は、実行前にコメントをSQLクエリに注入することで、[SQL commenter](https://google.github.io/sqlcommenter/spec/)を使ってコンテキストを伝搬してもかまいません（MAY）。SQL commenterによるコンテキスト伝搬は、デフォルトで有効にすべきではありません（SHOULD NOT）が、計装はユーザーがオプトインできるようにしてもかまいません（MAY）。 計装の実装は、クエリの末尾にコメントを**追記**すべきです（SHOULD）。個々のデータベースシステムに関するセマンティック規約は、そのデータベースシステム固有の要件や好みに応じて、異なる位置、エンコーディング、スキーマを含む異なる形式を指定してもかまいません（MAY）。 計装は、ユーザーがグローバルなプロパゲーターを上書きするプロパゲーターを渡せるようにすべきです（SHOULD）。ユーザーによってプロパゲーターが提供されない場合、計装はグローバルなプロパゲーターを使用すべきです（SHOULD）。 **例:** - W3C TraceContextプロパゲーターを使ったクエリ `SELECT * FROM songs` の場合: ```sql SELECT * FROM songs /*traceparent='00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',tracestate='congo%3Dt61rcWkgMzE%2Crojo%3D00f067aa0ba902b7'*/ ``` `traceparent` や `tracestate` のような高カーディナリティなコメントをクエリに追加すると、一部のデータベースシステムでパフォーマンスに影響する可能性があることに注意してください。たとえば以下のような場合です。 - MySQLのプリペアドステートメント。詳細は[この関連issue](https://github.com/google/sqlcommenter/issues/284)を参照してください。 - OracleとSQL Serverでは、プリペアドステートメントと非プリペアドステートメントの両方。 - `service.name` が `shoppingcart` であるキャリアに `service.name` を注入するカスタムプロパゲーターを使ったクエリ `SELECT * FROM songs` の場合: ```sql SELECT * FROM songs /*service.name='shoppingcart'*/ ``` ## Semantic conventions for specific database technologies 以下のデータベース技術については、より具体的なセマンティック規約が定義されています。 * [AWS DynamoDB](/works/otel-specs-ja/semconv/db/dynamodb/): *AWS DynamoDB*に関するセマンティック規約。 * [Cassandra](/works/otel-specs-ja/semconv/db/cassandra/): *Cassandra*に関するセマンティック規約。 * [Azure Cosmos DB](/works/otel-specs-ja/semconv/db/cosmosdb/): *Azure Cosmos DB*に関するセマンティック規約。 * [CouchDB](/works/otel-specs-ja/semconv/db/couchdb/): *CouchDB*に関するセマンティック規約。 * [Elasticsearch](/works/otel-specs-ja/semconv/db/elasticsearch/): *Elasticsearch*に関するセマンティック規約。 * [HBase](/works/otel-specs-ja/semconv/db/hbase/): *HBase*に関するセマンティック規約。 * [MongoDB](/works/otel-specs-ja/semconv/db/mongodb/): *MongoDB*に関するセマンティック規約。 * [Microsoft SQL Server](/works/otel-specs-ja/semconv/db/sql-server/): *Microsoft SQL Server*に関するセマンティック規約。 * [Redis](/works/otel-specs-ja/semconv/db/redis/): *Redis*に関するセマンティック規約。 * [SQL](/works/otel-specs-ja/semconv/db/sql/): *SQL*データベースに関するセマンティック規約。 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status