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


# Microsoft Azure Cosmos DBクライアント操作に関するセマンティック規約

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

[Microsoft Cosmos DB](https://azure.microsoft.com/products/cosmos-db/)に関するセマンティック規約は、[データベースに関するセマンティック規約](/works/otel-specs-ja/semconv/db/)を拡張・オーバーライドします。

## Spans

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

**Status:** ![Development](https://img.shields.io/badge/-development-blue)

Cosmos DBの計装には、論理的なデータベース呼び出しを表す呼び出しレベルのスパンが含まれ、これは[データベースクライアントのスパンに関する全般的なセマンティック規約](/works/otel-specs-ja/semconv/db/database-spans/)に従います。

接続モード（GatewayまたはDirect）によっては、ネットワーク呼び出しを表す追加のスパンが作成される場合もあります。
この文書で説明するセマンティック規約は、呼び出しレベルのスパンにのみ適用されます。

`db.system.name` は `"azure.cosmosdb"` に設定しなければならず（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.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) | `Required` | string | 実行されている操作またはコマンドの名前。 [1] | `create_item`; `query_items`; `read_item` |
| [`azure.cosmosdb.connection.mode`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/azure/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [2] | string | Cosmosクライアントの接続モード。 | `gateway`; `direct` |
| [`azure.cosmosdb.consistency.level`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/azure/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If available. | string | アカウントまたはリクエストの[一貫性レベル](https://learn.microsoft.com/azure/cosmos-db/consistency-levels)。 | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong`; `Session` |
| [`azure.cosmosdb.operation.contacted_regions`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/azure/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If available. | string[] | 操作中に接続されたリージョンの、接続された順序でのリスト。複数のリージョンが列挙されている場合、その操作が複数のリージョンに対して、つまりクロスリージョンの呼び出しとして実行されたことを示す。 [3] | `["North Central US", "Australia East", "Australia Southeast"]` |
| [`azure.cosmosdb.operation.request_charge`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/azure/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` when available | double | 操作によって消費されたリクエストユニットの数。 | `46.18`; `1.0` |
| [`azure.cosmosdb.response.sub_status_code`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/azure/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` when response was received and contained sub-code. | int | Cosmos DBのサブステータスコード。 | `1000`; `1002` |
| [`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` if available | string | Cosmos DBのコンテナ名。 [4] | `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 | サーバーアドレスとポートの範囲内で完全修飾された、データベースの名前。 | `customers`; `test.users` |
| [`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) | `Conditionally Required` if response was received and returned any rows | int | Cosmos DBの結果セットの行数。 | `10`; `20` |
| [`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` if response was received | string | Cosmos DBのステータスコード。 [5] | `200`; `201` |
| [`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 | 操作が終了した際のエラーのクラスを記述する。 [6] | `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` If not default (443). | int | サーバーのポート番号。 [7] | `80`; `8080`; `443` |
| [`azure.client.id`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/azure/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | クライアントインスタンスの一意な識別子。 | `3ba4827d-4422-483f-b59f-85b74211c11d`; `storage-client-1` |
| [`azure.cosmosdb.request.body.size`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/azure/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | リクエストペイロードのサイズ（バイト単位）。 | |
| [`azure.resource_provider.namespace`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/azure/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | クライアントによって認識された、[Azureリソースプロバイダーの名前空間](https://learn.microsoft.com/azure/azure-resource-manager/management/azure-services-resource-providers)。 [8] | `Microsoft.DocumentDB` |
| [`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 | バッチ操作に含まれるデータベース操作の数。 [9] | `2`; `3`; `4` |
| [`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` | string | 実行されているデータベースクエリ。 [10] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` |
| [`db.stored_procedure.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) | `Recommended` [11] | string | データベース内のストアドプロシージャの名前。 [12] | `GetCustomer` |
| [`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 | データベースホストの名前。 [13] | `example.com`; `10.1.2.80`; `/tmp/my.sock` |
| [`user_agent.original`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/user-agent/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Cosmos DB SDKによって生成される完全なユーザーエージェント文字列 [14] | `cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|` |
| [`db.query.parameter.<key>`](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 | データベースクエリのパラメータ。`<key>` はパラメータ名であり、属性値はパラメータ値の文字列表現である。 [15] | `someval`; `55` |

**[1] `db.operation.name`:** `db.operation.name` には、以下の既知の値の一覧があります。
これらのいずれかが該当する場合、対応する値を使用しなければなりません。

バッチ操作:

- `execute_batch`

バルク操作:

- `execute_bulk` は、複数の操作をバルク実行することを表す
  [`executeBulkOperations`](https://javadoc.io/doc/com.azure/azure-cosmos/latest/com/azure/cosmos/CosmosAsyncContainer.html#executeBulkOperations(reactor.core.publisher.Flux))
  のようなメソッドについて報告されるスパンで使用すべきです（SHOULD）。
- `bulk_{operation name}`（`bulk_create_item`、`bulk_upsert_item` など）は、バルク内の個々の操作を記述するスパン（それらが報告される場合）で使用すべきです（SHOULD）。
  このパターンは、計装が各操作についてスパンを作成する一方で、操作がバッファリングされてバルクで実行される場合に使用すべきです（SHOULD）。
  たとえば、`Microsoft.Azure.Cosmos` クライアントで[`AllowBulkExecution`](https://learn.microsoft.com/dotnet/api/microsoft.azure.cosmos.cosmosclientoptions.allowbulkexecution)プロパティが設定されている場合に該当します。

変更フィード操作:

- `query_change_feed`

コンフリクト操作:

- `delete_conflict`
- `query_conflicts`
- `read_all_conflicts`
- `read_conflict`

コンテナ操作:

- `create_container`
- `create_container_if_not_exists`
- `delete_container`
- `query_containers`
- `read_all_containers`
- `read_container`
- `read_container_throughput`
- `replace_container`
- `replace_container_throughput`

データベース操作:

- `create_database`
- `create_database_if_not_exists`
- `delete_database`
- `query_databases`
- `read_all_databases`
- `read_database`
- `read_database_throughput`
- `replace_database_throughput`

暗号化キー操作:

- `create_client_encryption_key`
- `query_client_encryption_keys`
- `read_all_client_encryption_keys`
- `read_client_encryption_key`
- `replace_client_encryption_key`

アイテム操作:

- `create_item`
- `delete_all_items_by_partition_key`
- `delete_item`
- `patch_item`
- `query_items`
- `read_all_items`
- `read_all_items_of_logical_partition`
- `read_many_items`
- `read_item`
- `replace_item`
- `upsert_item`

パーミッション操作:

- `create_permission`
- `delete_permission`
- `query_permissions`
- `read_all_permissions`
- `read_permission`
- `replace_permission`
- `upsert_permission`

ストアドプロシージャ操作:

- `create_stored_procedure`
- `delete_stored_procedure`
- `execute_stored_procedure`
- `query_stored_procedures`
- `read_all_stored_procedures`
- `read_stored_procedure`
- `replace_stored_procedure`

トリガー操作:

- `create_trigger`
- `delete_trigger`
- `query_triggers`
- `read_all_triggers`
- `read_trigger`
- `replace_trigger`

ユーザー操作:

- `create_user`
- `delete_user`
- `query_users`
- `read_all_users`
- `read_user`
- `replace_user`
- `upsert_user`

ユーザー定義関数操作:

- `create_user_defined_function`
- `delete_user_defined_function`
- `query_user_defined_functions`
- `read_all_user_defined_functions`
- `read_user_defined_function`

これらのいずれも該当しない場合、言語に依存しない、クライアントのメソッド名をsnake_caseで表現した値を使用することが推奨されます（RECOMMENDED）。計装は、新しい操作を導入する際に追加の値を文書化すべきです（SHOULD）。

**[2] `azure.cosmosdb.connection.mode`:** `gateway` 以外の場合（デフォルト値は `gateway` であるとみなされます）。

**[3] `azure.cosmosdb.operation.contacted_regions`:** リージョン名は、[Azure Location API](https://learn.microsoft.com/rest/api/resources/subscriptions/list-locations)の `displayName` の形式に一致します。

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

**[5] `db.response.status_code`:** 4xxおよび5xx範囲のレスポンスコードは、エラーとみなすべきです（SHOULD）。

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

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

**[8] `azure.resource_provider.namespace`:** `azure.resource_provider.namespace` 属性が設定される場合、Cosmos DBクライアントによって実行されるすべての操作について `Microsoft.DocumentDB` に設定しなければなりません（MUST）。

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

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

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

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

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

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

**[14] `user_agent.original`:** このユーザーエージェント値はSDKによって生成され、以下の組み合わせから構成されます。<br> `sdk_version`：SDKの現在のバージョン。例: 'cosmos-netstandard-sdk/3.23.0'<br> `direct_pkg_version`：Cosmos DB SDKが使用するDirectパッケージのバージョン。例: '3.23.1'<br> `number_of_client_instances`：アプリケーションによって作成されたCosmosクライアントインスタンスの数。例: '1'<br> `type_of_machine_architecture`：マシンアーキテクチャ。例: 'X64'<br> `operating_system`：オペレーティングシステム。例: 'Linux 5.4.0-1098-azure 104 18'<br> `runtime_framework`：ランタイムフレームワーク。例: '.NET Core 3.1.32'<br> `failover_information`：リージョンフェイルオーバーが有効かどうかを判定するために生成されるキー。
   形式は Reg-{D（ディスカバリー無効）}-S（アプリケーションリージョン）|L（優先リージョンのリスト）|N（None、ユーザーが未設定）。
   デフォルト値は "NS" です。

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

以下の属性は、サンプリングの判断を行う上で重要な場合があり、**スパン作成時に**（提供する場合は）提供すべきです（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/)
* [`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/)

---

`azure.cosmosdb.connection.mode` には、以下の既知の値の一覧があります。これらのいずれかが該当する場合、対応する値を使用しなければなりません（MUST）。それ以外の場合は、独自の値を使用してもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `direct` | Direct接続。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `gateway` | Gateway（HTTP）接続。 | ![Development](https://img.shields.io/badge/-development-blue) |

---

`azure.cosmosdb.consistency.level` には、以下の既知の値の一覧があります。これらのいずれかが該当する場合、対応する値を使用しなければなりません（MUST）。それ以外の場合は、独自の値を使用してもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `BoundedStaleness` | Bounded Staleness | ![Development](https://img.shields.io/badge/-development-blue) |
| `ConsistentPrefix` | Consistent Prefix | ![Development](https://img.shields.io/badge/-development-blue) |
| `Eventual` | Eventual | ![Development](https://img.shields.io/badge/-development-blue) |
| `Session` | Session | ![Development](https://img.shields.io/badge/-development-blue) |
| `Strong` | Strong | ![Development](https://img.shields.io/badge/-development-blue) |

---

`error.type` には、以下の既知の値の一覧があります。これらのいずれかが該当する場合、対応する値を使用しなければなりません（MUST）。それ以外の場合は、独自の値を使用してもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `_OTHER` | 計装が独自の値を定義していない場合に使用するフォールバックのエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |

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

### Example

| Key                                       | Value                                                                                                   |
| :---------------------------------------- | :------------------------------------------------------------------------------------------------------ |
| Span name                                 | `"read_item orders"`                                                                                    |
| `azure.client.id`                         | `"3ba4827d-4422-483f-b59f-85b74211c11d"`                                                                |
| `azure.cosmosdb.operation.request_charge` | `7.43`                                                                                                  |
| `azure.cosmosdb.request.body.size`        | `20`                                                                                                    |
| `azure.cosmosdb.response.sub_status_code` | `0`                                                                                                     |
| `azure.resource_provider.namespace`       | `"Microsoft.DocumentDB"`                                                                                |
| `db.system.name`                          | `"azure.cosmosdb"`                                                                                      |
| `db.collection.name`                      | `"orders"`                                                                                              |
| `db.namespace`                            | `"ShopDb"`                                                                                              |
| `db.operation.name`                       | `"read_item"`                                                                                           |
| `db.response.status_code`                 | `201`                                                                                                   |
| `server.address`                          | `"account.documents.azure.com"`                                                                         |
| `user_agent.original`                     | `"cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|"` |

## Metrics

以下のメトリクスは、Azure Cosmos DBクライアント操作のパフォーマンスと動作に関する知見を提供します。

### Metric: `db.client.operation.duration`

このメトリクスは[推奨](/works/otel-specs-ja/semconv/general/signal-requirement-level/#recommended)されています。

このメトリクスは、Azure Cosmos DB操作にかかった合計時間を計測します。このメトリクスは、共通の[db.client.operation.duration](/works/otel-specs-ja/semconv/db/database-metrics/#metric-dbclientoperationduration)の定義に従います。

ディメンションについては、[azure.cosmosdb.client.operation.request_charge](#metric-azurecosmosdbclientoperationrequest_charge)メトリクスを参照してください。

### Metric: `db.client.response.returned_rows`

このメトリクスは[推奨](/works/otel-specs-ja/semconv/general/signal-requirement-level/#recommended)されています。

このメトリクスは、Azure Cosmos DBにおいてクエリまたはフィード操作によって返された項目数を計測します。これは、高いレイテンシー、メモリやCPU使用量の増加、ネットワーク呼び出しの失敗の原因となりうる応答サイズを特定するのに役立ちます。このメトリクスは、共通の[`db.client.response.returned_rows`](/works/otel-specs-ja/semconv/db/database-metrics/#metric-dbclientresponsereturned_rows)の定義に従います。

ディメンションについては、[azure.cosmosdb.client.operation.request_charge](#metric-azurecosmosdbclientoperationrequest_charge)メトリクスを参照してください。

### Metric: `azure.cosmosdb.client.operation.request_charge`

このメトリクスは[推奨](/works/otel-specs-ja/semconv/general/signal-requirement-level/#recommended)されています。

このメトリクスは、Azure Cosmos DBにおいて各操作が消費するリクエストユニットを計測します。リクエストユニットはAzure Cosmos DBデータベース内のスループット制御の一形態として機能するため、その使用状況を監視することはスロットリングを回避するうえで重要です。

このメトリクスは、[`ExplicitBucketBoundaries` advisoryパラメータ](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.59.0/specification/metrics/api.md#instrument-advisory-parameters)を `[ 1, 5, 10, 25, 50, 100, 250, 500, 1000]` として指定すべきです（SHOULD）。

バケット構成の説明:

1. 1, 5, 10: 低使用量レベル。これらの小さなバケットは、最小限のリクエストユニットしか消費しない操作を精密に追跡できるようにします。これは、基本的な読み取りリクエストや小さなクエリのような軽量な操作にとって重要であり、これらの操作ではリソース使用量を最適化すべきです。これらの低使用量レベルを監視することで、アプリケーションが意図せず必要以上のリソースを使用していないことを確認できます。
2. 25, 50: 中程度の使用量レベル。これらの範囲は、多くのアプリケーションで典型的な、より中程度の操作を捉えます。たとえば、適度なデータ量を返すクエリや標準的なCRUD操作は、これらの範囲に収まる場合があります。これらのバケットの使用パターンを特定することで、日常的な操作における効率上の問題を検出できます。
3. 100, 250: より高い使用量レベル。これらの境界は、複雑なクエリや大きなトランザクションなど、大量のリソースを必要とする可能性のある操作を表します。これらの範囲でのリクエストユニットを監視することで、パフォーマンスのボトルネックやコストのかかるクエリを特定できます。
4. 500, 1000: 非常に高い使用量レベル。これらのバケットは、大量のリクエストユニットを消費する操作を捉え、コストの高いクエリやバッチ処理を示唆する可能性があります。こうした高いリクエストユニット使用の頻度とパターンを理解することは、パフォーマンスの最適化とアプリケーションがプロビジョニングされたスループットの制限内に収まるようにするうえで重要です。

<!-- semconv metric.azure.cosmosdb.client.operation.request_charge -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `azure.cosmosdb.client.operation.request_charge` | Histogram | `{request_unit}` | 操作によって消費された[リクエストユニット](https://learn.microsoft.com/azure/cosmos-db/request-units)。 | ![Development](https://img.shields.io/badge/-development-blue) | |

**Attributes:**

| Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`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) | `Required` | string | 実行されている操作またはコマンドの名前。 [1] | `findAndModify`; `HMSET`; `SELECT` |
| [`azure.cosmosdb.consistency.level`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/azure/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If available. | string | アカウントまたはリクエストの[一貫性レベル](https://learn.microsoft.com/azure/cosmos-db/consistency-levels)。 | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong`; `Session` |
| [`azure.cosmosdb.response.sub_status_code`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/azure/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` when response was received and contained sub-code. | int | Cosmos DBのサブステータスコード。 | `1000`; `1002` |
| [`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` If available. | string | Cosmos DBのコンテナ名。 [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 | サーバーアドレスとポートの範囲内で完全修飾された、データベースの名前。 | `customers`; `test.users` |
| [`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` [3] | string | データベースの応答ステータスコード。 [4] | `102`; `ORA-17002`; `08P01`; `404` |
| [`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 | 操作が終了した際のエラーのクラスを記述する。 [5] | `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` [6] | int | サーバーのポート番号。 [7] | `80`; `8080`; `443` |
| [`azure.cosmosdb.operation.contacted_regions`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/azure/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` If available | string[] | 操作中に接続されたリージョンの、接続された順序でのリスト。複数のリージョンが列挙されている場合、その操作が複数のリージョンに対して、つまりクロスリージョンの呼び出しとして実行されたことを示す。 [8] | `["North Central US", "Australia East", "Australia Southeast"]` |
| [`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 | データベースホストの名前。 [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` |

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

データベースシステムが非バッチ操作において複数の操作を含むクエリテキストをサポートする場合、操作名は `db.query.text` から抽出してはなりません（SHOULD NOT）。

操作名にスペースが含まれる可能性がある場合、連続する複数のスペースは単一のスペースに正規化すべきです（SHOULD）。

バッチ操作については、個々の操作が同じ操作名を持つことがわかっている場合、その操作名の前に `BATCH ` を付けて使用すべきです（SHOULD）。そうでない場合、`db.operation.name` は `BATCH`、またはより適切であれば他のデータベースシステム固有の用語にすべきです（SHOULD）。

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

**[3] `db.response.status_code`:** 操作が失敗し、ステータスコードが利用可能な場合。

**[4] `db.response.status_code`:** データベースによって返されたステータスコード。通常はエラーコードを表しますが、部分的な成功、警告、または様々な種類の成功結果の区別を表すこともあります。
個々のデータベースシステムに関するセマンティック規約は、そのシステムにおいて `db.response.status_code` が何を意味するかを文書化すべきです（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] `azure.cosmosdb.operation.contacted_regions`:** リージョン名は、[Azure Location API](https://learn.microsoft.com/rest/api/resources/subscriptions/list-locations)の `displayName` の形式に一致します。

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

---

`azure.cosmosdb.consistency.level` には、以下の既知の値の一覧があります。これらのいずれかが該当する場合、対応する値を使用しなければなりません（MUST）。それ以外の場合は、独自の値を使用してもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `BoundedStaleness` | Bounded Staleness | ![Development](https://img.shields.io/badge/-development-blue) |
| `ConsistentPrefix` | Consistent Prefix | ![Development](https://img.shields.io/badge/-development-blue) |
| `Eventual` | Eventual | ![Development](https://img.shields.io/badge/-development-blue) |
| `Session` | Session | ![Development](https://img.shields.io/badge/-development-blue) |
| `Strong` | Strong | ![Development](https://img.shields.io/badge/-development-blue) |

---

`error.type` には、以下の既知の値の一覧があります。これらのいずれかが該当する場合、対応する値を使用しなければなりません（MUST）。それ以外の場合は、独自の値を使用してもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `_OTHER` | 計装が独自の値を定義していない場合に使用するフォールバックのエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |

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

### Metric: `azure.cosmosdb.client.active_instance.count`

このメトリクスは[推奨](/works/otel-specs-ja/semconv/general/signal-requirement-level/#recommended)されています。

このメトリクスは、ある時点でのアクティブなインスタンス数を計測します。ベストプラクティスでは、Azure Cosmos DBアカウントごとに、SDKクライアントのインスタンスは理想的には1つだけであるべきとされています。同一のアカウントに対して単一プロセス内でSDKクライアントの複数のインスタンスを持つと、CPUやメモリに関連する問題を引き起こす可能性があります。

<!-- semconv metric.azure.cosmosdb.client.active_instance.count -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `azure.cosmosdb.client.active_instance.count` | UpDownCounter | `{instance}` | アクティブなクライアントインスタンスの数。 | ![Development](https://img.shields.io/badge/-development-blue) | |

**Attributes:**

| Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`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` [1] | int | サーバーのポート番号。 [2] | `80`; `8080`; `443` |
| [`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 | データベースホストの名前。 [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` |

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

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

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

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

[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
[MetricRecommended]: /works/otel-specs-ja/semconv/general/signal-requirement-level/#recommended