この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/semconv/db/cosmosdb/

翻訳元: open-telemetry/semantic-conventions v1.44.0（コミット e10a930）

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

ステータス: Development

Microsoft Cosmos DBに関するセマンティック規約は、データベースに関するセマンティック規約を拡張・オーバーライドします。

Spans

Status:

Cosmos DBの計装には、論理的なデータベース呼び出しを表す呼び出しレベルのスパンが含まれ、これはデータベースクライアントのスパンに関する全般的なセマンティック規約に従います。

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

db.system.name は "azure.cosmosdb" に設定しなければならず（MUST）、スパン作成時に提供すべきです（SHOULD）。

スパン名は、全般的なデータベースのスパン名に関する規約に従うべきです（SHOULD）。

スパン種別は CLIENT にすべきです（SHOULD）。

スパンステータスは、エラーの記録の文書に従うべきです（SHOULD）。

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
db.operation.name		Required	string	実行されている操作またはコマンドの名前。 [1]	create_item; query_items; read_item
azure.cosmosdb.connection.mode		Conditionally Required [2]	string	Cosmosクライアントの接続モード。	gateway; direct
azure.cosmosdb.consistency.level		Conditionally Required If available.	string	アカウントまたはリクエストの一貫性レベル。	Eventual; ConsistentPrefix; BoundedStaleness; Strong; Session
azure.cosmosdb.operation.contacted_regions		Conditionally Required If available.	string[]	操作中に接続されたリージョンの、接続された順序でのリスト。複数のリージョンが列挙されている場合、その操作が複数のリージョンに対して、つまりクロスリージョンの呼び出しとして実行されたことを示す。 [3]	["North Central US", "Australia East", "Australia Southeast"]
azure.cosmosdb.operation.request_charge		Conditionally Required when available	double	操作によって消費されたリクエストユニットの数。	46.18; 1.0
azure.cosmosdb.response.sub_status_code		Conditionally Required when response was received and contained sub-code.	int	Cosmos DBのサブステータスコード。	1000; 1002
db.collection.name		Conditionally Required if available	string	Cosmos DBのコンテナ名。 [4]	public.users; customers
db.namespace		Conditionally Required If available.	string	サーバーアドレスとポートの範囲内で完全修飾された、データベースの名前。	customers; test.users
db.response.returned_rows		Conditionally Required if response was received and returned any rows	int	Cosmos DBの結果セットの行数。	10; 20
db.response.status_code		Conditionally Required if response was received	string	Cosmos DBのステータスコード。 [5]	200; 201
error.type		Conditionally Required If and only if the operation failed.	string	操作が終了した際のエラーのクラスを記述する。 [6]	timeout; java.net.UnknownHostException; server_certificate_invalid; 500
server.port		Conditionally Required If not default (443).	int	サーバーのポート番号。 [7]	80; 8080; 443
azure.client.id		Recommended	string	クライアントインスタンスの一意な識別子。	3ba4827d-4422-483f-b59f-85b74211c11d; storage-client-1
azure.cosmosdb.request.body.size		Recommended	int	リクエストペイロードのサイズ（バイト単位）。
azure.resource_provider.namespace		Recommended	string	クライアントによって認識された、Azureリソースプロバイダーの名前空間。 [8]	Microsoft.DocumentDB
db.operation.batch.size		Recommended	int	バッチ操作に含まれるデータベース操作の数。 [9]	2; 3; 4
db.query.text		Recommended	string	実行されているデータベースクエリ。 [10]	SELECT * FROM wuser_table where username = ?; SET mykey ?
db.stored_procedure.name		Recommended [11]	string	データベース内のストアドプロシージャの名前。 [12]	GetCustomer
server.address		Recommended	string	データベースホストの名前。 [13]	example.com; 10.1.2.80; /tmp/my.sock
user_agent.original		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>		Opt-In	string	データベースクエリのパラメータ。<key> はパラメータ名であり、属性値はパラメータ値の文字列表現である。 [15]	someval; 55

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

バッチ操作:

• execute_batch

バルク操作:

• execute_bulk は、複数の操作をバルク実行することを表す executeBulkOperations のようなメソッドについて報告されるスパンで使用すべきです（SHOULD）。
• bulk_{operation name}（bulk_create_item、bulk_upsert_item など）は、バルク内の個々の操作を記述するスパン（それらが報告される場合）で使用すべきです（SHOULD）。 このパターンは、計装が各操作についてスパンを作成する一方で、操作がバッファリングされてバルクで実行される場合に使用すべきです（SHOULD）。 たとえば、Microsoft.Azure.Cosmos クライアントで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の 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を含む）を受け付けるという理由だけでは、データベース呼び出しはバッチ操作にはなりません。

同じパラメータ化された操作をパラメータセットとともに実行するバッチ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 のサニタイズを参照してください。 バッチ操作については、個々の操作が同じクエリテキストを持つことがわかっている場合、そのクエリテキストを使用すべきです（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によって生成され、以下の組み合わせから構成されます。
sdk_version：SDKの現在のバージョン。例: ‘cosmos-netstandard-sdk/3.23.0’
direct_pkg_version：Cosmos DB SDKが使用するDirectパッケージのバージョン。例: ‘3.23.1’
number_of_client_instances：アプリケーションによって作成されたCosmosクライアントインスタンスの数。例: ‘1’
type_of_machine_architecture：マシンアーキテクチャ。例: ‘X64’
operating_system：オペレーティングシステム。例: ‘Linux 5.4.0-1098-azure 104 18’
runtime_framework：ランタイムフレームワーク。例: ‘.NET Core 3.1.32’
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
• db.namespace
• db.operation.name
• server.address
• server.port

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

Value	Description	Stability
direct	Direct接続。
gateway	Gateway（HTTP）接続。

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

Value	Description	Stability
BoundedStaleness	Bounded Staleness
ConsistentPrefix	Consistent Prefix
Eventual	Eventual
Session	Session
Strong	Strong

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

Value	Description	Stability
_OTHER	計装が独自の値を定義していない場合に使用するフォールバックのエラー値。

Example

Metrics

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

Metric: db.client.operation.duration

このメトリクスは推奨されています。

このメトリクスは、Azure Cosmos DB操作にかかった合計時間を計測します。このメトリクスは、共通のdb.client.operation.durationの定義に従います。

ディメンションについては、azure.cosmosdb.client.operation.request_chargeメトリクスを参照してください。

Metric: db.client.response.returned_rows

このメトリクスは推奨されています。

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

ディメンションについては、azure.cosmosdb.client.operation.request_chargeメトリクスを参照してください。

Metric: azure.cosmosdb.client.operation.request_charge

このメトリクスは推奨されています。

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

このメトリクスは、ExplicitBucketBoundaries advisoryパラメータを [ 1, 5, 10, 25, 50, 100, 250, 500, 1000] として指定すべきです（SHOULD）。

バケット構成の説明:

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

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
azure.cosmosdb.client.operation.request_charge	Histogram	{request_unit}	操作によって消費されたリクエストユニット。

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
db.operation.name		Required	string	実行されている操作またはコマンドの名前。 [1]	findAndModify; HMSET; SELECT
azure.cosmosdb.consistency.level		Conditionally Required If available.	string	アカウントまたはリクエストの一貫性レベル。	Eventual; ConsistentPrefix; BoundedStaleness; Strong; Session
azure.cosmosdb.response.sub_status_code		Conditionally Required when response was received and contained sub-code.	int	Cosmos DBのサブステータスコード。	1000; 1002
db.collection.name		Conditionally Required If available.	string	Cosmos DBのコンテナ名。 [2]	public.users; customers
db.namespace		Conditionally Required If available.	string	サーバーアドレスとポートの範囲内で完全修飾された、データベースの名前。	customers; test.users
db.response.status_code		Conditionally Required [3]	string	データベースの応答ステータスコード。 [4]	102; ORA-17002; 08P01; 404
error.type		Conditionally Required If and only if the operation failed.	string	操作が終了した際のエラーのクラスを記述する。 [5]	timeout; java.net.UnknownHostException; server_certificate_invalid; 500
server.port		Conditionally Required [6]	int	サーバーのポート番号。 [7]	80; 8080; 443
azure.cosmosdb.operation.contacted_regions		Recommended If available	string[]	操作中に接続されたリージョンの、接続された順序でのリスト。複数のリージョンが列挙されている場合、その操作が複数のリージョンに対して、つまりクロスリージョンの呼び出しとして実行されたことを示す。 [8]	["North Central US", "Australia East", "Australia Southeast"]
server.address		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の displayName の形式に一致します。

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

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

Value	Description	Stability
BoundedStaleness	Bounded Staleness
ConsistentPrefix	Consistent Prefix
Eventual	Eventual
Session	Session
Strong	Strong

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

Value	Description	Stability
_OTHER	計装が独自の値を定義していない場合に使用するフォールバックのエラー値。

Metric: azure.cosmosdb.client.active_instance.count

このメトリクスは推奨されています。

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

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
azure.cosmosdb.client.active_instance.count	UpDownCounter	{instance}	アクティブなクライアントインスタンスの数。

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
server.port		Conditionally Required [1]	int	サーバーのポート番号。 [2]	80; 8080; 443
server.address		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）。