> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/db/oracledb/


# Oracle Databaseに関するセマンティック規約

**ステータス**: [Mixed][DocumentStatus]

*Oracle Database*に関するセマンティック規約は、[データベースに関するセマンティック規約](/works/otel-specs-ja/semconv/db/)を拡張・上書きします。

## Spans

<!-- semconv span.db.oracledb.client -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

**Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid)

Oracle SQL Databaseへの呼び出しを表すスパンは、[データベースクライアントのスパンに関する全般的なセマンティック規約](/works/otel-specs-ja/semconv/db/database-spans/)に準拠します。

`db.system.name` は `"oracle.db"` に設定しなければならず（MUST）、**スパン作成時に**提供すべきです（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.namespace`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If available without an additional network call. | string | 接続に関連付けられたデータベースの一意な識別子。 [1] | `ORCL1`; `ORCL2`; `ORCL3` |
| [`db.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If response has ended with warning or an error. | string | 文字列として記録された[Oracle Databaseのエラー番号](https://docs.oracle.com/en/error-help/db/)。 [2] | `ORA-02813`; `ORA-02613` |
| [`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 | 操作が終了した際のエラーのクラスを記述する。 [3] | `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` [4] | int | サーバーのポート番号。 [5] | `80`; `8080`; `443` |
| [`db.collection.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` [6] | string | データベース内のコレクション（テーブル、コンテナ）の名前。 [7] | `public.users`; `customers` |
| [`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.operation.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` [9] | string | 実行されている操作またはコマンドの名前。 [10] | `EXECUTE`; `INSERT` |
| [`db.query.summary`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` [11] | string | データベースクエリの低カーディナリティな要約。 [12] | `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` [13] | string | 実行されているデータベースクエリ。 [14] | `SELECT * FROM wuser_table where username = ?` |
| [`db.stored_procedure.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` [15] | string | データベース内のストアドプロシージャの名前。 [16] | `GetCustomer` |
| [`oracle.db.domain`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/oracledb/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | 接続に関連付けられたデータベースドメイン。 [17] | `example.com`; `corp.internal`; `prod.db.local` |
| [`oracle.db.instance.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/oracledb/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | Oracle Real Application Clusters環境において、接続にバインドされているインスタンス名。 [18] | `ORCL1`; `ORCL2`; `ORCL3` |
| [`oracle.db.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/oracledb/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | 接続に関連付けられたデータベース名。 [19] | `ORCL1`; `FREE` |
| [`oracle.db.pdb`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/oracledb/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | 接続に関連付けられたプラガブルデータベース（PDB）名。 [20] | `PDB1`; `FREEPDB` |
| [`oracle.db.service`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/oracledb/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | 現在、データベース接続に関連付けられているサービス名。 [21] | `order-processing-service`; `db_low.adb.oraclecloud.com`; `db_high.adb.oraclecloud.com` |
| [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | データベースホストの名前。 [22] | `example.com`; `10.1.2.80`; `/tmp/my.sock` |
| [`db.query.parameter.<key>`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | データベースクエリのパラメータ。`<key>` はパラメータ名であり、属性値はパラメータ値の文字列表現である。 [23] | `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 | 操作によって返された行数。 [24] | `10`; `30`; `1000` |

**[1] `db.namespace`:** `DB_UNIQUE_NAME` パラメータの値を使用します。これはデータベースのグローバルに一意な識別子を定義するものであり、エンタープライズ全体で一意でなければなりません。

**[2] `db.response.status_code`:** Oracle Databaseのエラーコードはベンダー固有のエラーコードであり、[SQLSTATE](https://wikipedia.org/wiki/SQLSTATE)の規約には従いません。すべてのOracle Databaseのエラーコードはエラーとして扱うべきです（SHOULD）。

**[3] `error.type`:** `error.type` は、データベースまたはクライアントライブラリによって返された `db.response.status_code`、または発生した例外の正式名称と一致すべきです（SHOULD）。
正式な例外型名を使用する場合、計装は最も関連性の高い型を報告するよう最善を尽くすべきです（SHOULD）。たとえば、元の例外が汎用的な例外にラップされている場合、元の例外を優先すべきです（SHOULD）。
計装は、`error.type` がどのように設定されるかを文書化すべきです（SHOULD）。

**[4] `server.port`:** このDBMSのデフォルトポート以外のポートを使用しており、かつ `server.address` が設定されている場合。

**[5] `server.port`:** クライアント側から観測され、かつ中間者を介して通信している場合、`server.port` は、利用可能であれば、あらゆる中間者（たとえばプロキシ）の背後にあるサーバーポートを表すべきです（SHOULD）。

**[6] `db.collection.name`:** 操作が、複数のコレクション名をサポートしない高レベルAPIを介して実行される場合。

**[7] `db.collection.name`:** コレクション名は `db.query.text` から抽出してはなりません（SHOULD NOT）。

**[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.operation.name`:** 操作が、複数の操作名をサポートしない高レベルAPIを介して実行される場合。

**[10] `db.operation.name`:** 操作名は `db.query.text` から抽出してはなりません（SHOULD NOT）。

**[11] `db.query.summary`:** 計装フックを通じて利用可能な場合、または計装がクエリ要約の生成をサポートしている場合。

**[12] `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）。

**[13] `db.query.text`:** 非パラメータ化クエリテキストは、機密データを除外するサニタイズ（たとえばクエリテキスト中のすべてのリテラル値をマスクするなど）が行われていない限り、デフォルトで収集すべきではありません（SHOULD NOT）。[`db.query.text` のサニタイズ](/works/otel-specs-ja/semconv/db/database-spans/#sanitization-of-dbquerytext)を参照してください。
パラメータ化クエリテキストはデフォルトで収集すべきです（SHOULD）（クエリパラメータの値自体はオプトインです。[`db.query.parameter.<key>`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) を参照してください）。

**[14] `db.query.text`:** サニタイズについては[`db.query.text` のサニタイズ](/works/otel-specs-ja/semconv/db/database-spans/#sanitization-of-dbquerytext)を参照してください。
バッチ操作については、個々の操作が同じクエリテキストを持つことがわかっている場合、そのクエリテキストを使用すべきです（SHOULD）。そうでない場合、個々のクエリテキストはすべて、セパレーター `; `、またはより適切であれば他のデータベースシステム固有のセパレーターで連結すべきです（SHOULD）。
パラメータ化クエリテキストはサニタイズすべきではありません（SHOULD NOT）。パラメータ化クエリテキストには機密データが含まれる可能性がありますが、パラメータ化クエリを使用することで、ユーザーは機密データがパラメータ値として渡されるという強い意図を示していることになり、デフォルトでクエリテキストの静的な部分を取得することによるオブザーバビリティ上の利点が、そのリスクを上回ります。

**[15] `db.stored_procedure.name`:** 操作が特定のストアドプロシージャに適用される場合。

**[16] `db.stored_procedure.name`:** 値は、大文字小文字の正規化を試みずに、アプリケーションから提供されたとおりに取得することが推奨されます（RECOMMENDED）。

バッチ操作については、個々の操作が同じストアドプロシージャ名を持つことがわかっている場合、そのストアドプロシージャ名を使用すべきです（SHOULD）。

**[17] `oracle.db.domain`:** この属性は `v$parameter` に公開されている `DB_DOMAIN` 初期化パラメータの値に設定すべきです（SHOULD）。`DB_DOMAIN` はグローバルデータベース名のドメイン部分を定義するものであり、データベースが分散環境の一部である場合、またはそうなる可能性がある場合に設定すべきです（SHOULD）。値は、ピリオドで区切られた1つ以上の有効な識別子（英数字のASCII文字）で構成されます。

**[18] `oracle.db.instance.name`:** 1つのデータベースサービスに複数のインスタンスが関連付けられることがあります。この属性は、接続が現在バインドされている一意のインスタンス名を示します。RAC構成でないデータベースでは、この値はデフォルトで `oracle.db.name` になります。

**[19] `oracle.db.name`:** この属性は `v$parameter` に公開されているパラメータ `DB_NAME` の値に設定すべきです（SHOULD）。

**[20] `oracle.db.pdb`:** この属性は、セッションが現在接続しているPDBを反映すべきです（SHOULD）。計装が追加のクエリ（`SELECT SYS_CONTEXT` など）を発行せずに、各操作についてアクティブなPDB名を確実に取得できない場合、接続確立時に指定されたPDB名にフォールバックすることが推奨されます（RECOMMENDED）。

**[21] `oracle.db.service`:** 接続の有効なサービス名は、その生存期間中に変化することがあります。たとえばSQLの `ALTER SESSION` を実行した後などです。計装が追加のクエリ（`SELECT SYS_CONTEXT` など）を発行せずに、各操作について現在のサービス名を確実に取得できない場合、接続確立時に元々提供されたサービス名にフォールバックすることが推奨されます（RECOMMENDED）。

**[22] `server.address`:** クライアント側から観測され、かつ中間者を介して通信している場合、`server.address` は、利用可能であれば、あらゆる中間者の背後にあるサーバーアドレスを表すべきです（SHOULD）。

**[23] `db.query.parameter.<key>`:** クエリパラメータに名前がなく、インデックスのみで参照される場合、`<key>` は0始まりのインデックスにすべきです（SHOULD）。

`db.query.parameter.<key>` は、`db.query.text` に存在するパラメータ化されたプレースホルダーと対応すべきです（SHOULD）。

値は、大文字小文字の正規化やサニタイズを試みずに、アプリケーションから提供されたとおりに取得することが推奨されます（RECOMMENDED）。

計装は、値にPIIや機密情報が含まれる可能性があるため、デフォルトで `db.query.parameter.<key>` を取得すべきではありません（SHOULD NOT）。アプリケーションの運用者は、プライバシーやセキュリティ上の考慮に応じて特定のキーを有効化することが期待されます。

`db.query.parameter.<key>` はバッチ操作では取得すべきではありません（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）。

**[24] `db.response.returned_rows`:** 計装がスパン終了時点で観測した、データベース操作によって返された行数。

以下の属性は、サンプリングの判断を行う上で重要な場合があり、**スパン作成時に**（提供する場合は）提供すべきです（SHOULD）。

* [`db.namespace`](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/)
* [`oracle.db.domain`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/oracledb/)
* [`oracle.db.instance.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/oracledb/)
* [`oracle.db.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/oracledb/)
* [`oracle.db.pdb`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/oracledb/)
* [`oracle.db.service`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/oracledb/)
* [`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) |

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

## Context propagation

**ステータス**: [Development][DocumentStatus]

### V$SESSION.ACTION

計装は、クエリを実行する前にスパンコンテキストの一部（トレースID、スパンID、トレースフラグ、プロトコルバージョン）を注入することで、固定長64バイトの値を使う[V$SESSION.ACTION](https://docs.oracle.com/en/database/oracle/oracle-database/23/refrn/V-SESSION.html)を用いてコンテキストを伝搬してもかまいません（MAY）。たとえばW3C TraceContextを使う場合、[`traceparent`](https://www.w3.org/TR/trace-context/#traceparent-header)の文字列表現のみを注入すべきです（SHOULD）。コンテキスト注入はデフォルトで有効にすべきではありません（SHOULD NOT）が、計装はユーザーがオプトインできるようにしてもかまいません（MAY）。

`V$SESSION.ACTION` の値の長さは64バイトに制限されているため、可変長のコンテキスト部分（`tracestate`、`baggage`）は注入すべきではありません（SHOULD NOT）。

コンテキストを伝搬する計装は、SQL文と同じ物理接続上で `V$SESSION.ACTION` を更新しなければなりません（MUST）。

例:

言語によってOracle Databaseドライバの `V$SESSION.ACTION` 更新の実装が異なる場合があることに注意してください。

`traceparent` が `00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01` であるクエリ `SELECT * FROM songs` の場合:

SQL文と同じ物理接続上で以下のコマンドを実行します。

```sql
BEGIN
    DBMS_APPLICATION_INFO.SET_ACTION('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
END;
```

続いてクエリを実行します。

```sql
SELECT * FROM songs;
```

## Metrics

Oracle Databaseドライバの計装は、[データベースクライアントのメトリクスに関する全般的なセマンティック規約](/works/otel-specs-ja/semconv/db/database-metrics/)に従ってメトリクスを収集すべきです（SHOULD）。

`db.system.name` は `"oracle.db"` に設定しなければなりません（MUST）。

[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status