この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/semconv/db/sql-server/
翻訳元: open-telemetry/semantic-conventions v1.44.0（コミット e10a930）
Microsoft SQL Serverクライアントの操作に関するセマンティック規約
ステータス: 特に注記のない限りStable
Microsoft SQL Serverに関するセマンティック規約は、データベースに関するセマンティック規約を拡張・上書きします。
Spans
Status:
Microsoft SQL Serverへの呼び出しを表すスパンは、データベースクライアントのスパンに関する全般的なセマンティック規約に準拠します。
db.system.name は "microsoft.sql_server" に設定しなければならず（MUST）、スパン作成時に提供すべきです（SHOULD）。
スパン種別は CLIENT にすべきです（SHOULD）。
スパンステータスは、エラーの記録の文書に従うべきです（SHOULD）。
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
db.namespace |  | Conditionally Required If available without an additional network call. | string | 接続に関連付けられたデータベース。インスタンス名で修飾される。 [1] | instance1|products; customers |
db.response.status_code | | Conditionally Required If response has ended with warning or an error. | string | 文字列として表現されたMicrosoft SQL Serverのエラー番号。 [2] | 102; 40020 |
error.type | | Conditionally Required If and only if the operation failed. | string | 操作が終了した際のエラーのクラスを記述する。 [3] | timeout; java.net.UnknownHostException; server_certificate_invalid; 500 |
server.port | | Conditionally Required [4] | int | サーバーのポート番号。 [5] | 80; 8080; 443 |
db.collection.name | | Recommended [6] | string | データベース内のコレクション（テーブル、コンテナ）の名前。 [7] | public.users; customers |
db.operation.batch.size | | Recommended | int | バッチ操作に含まれるデータベース操作の数。 [8] | 2; 3; 4 |
db.operation.name | | Recommended [9] | string | 実行されている操作またはコマンドの名前。 [10] | EXECUTE; INSERT |
db.query.summary | | Recommended [11] | string | データベースクエリの低カーディナリティな要約。 [12] | SELECT wuser_table; INSERT shipping_details SELECT orders; get user by id |
db.query.text | | Recommended [13] | string | 実行されているデータベースクエリ。 [14] | SELECT * FROM wuser_table where username = ?; SET mykey ? |
db.stored_procedure.name | | Recommended [15] | string | データベース内のストアドプロシージャの名前。 [16] | GetCustomer |
server.address | | Recommended | string | データベースホストの名前。 [17] | example.com; 10.1.2.80; /tmp/my.sock |
db.query.parameter.<key> |  | Opt-In | string | データベースクエリのパラメータ。<key> はパラメータ名であり、属性値はパラメータ値の文字列表現である。 [18] | someval; 55 |
db.response.returned_rows | | Opt-In | int | 操作によって返された行数。 [19] | 10; 30; 1000 |
[1] db.namespace: デフォルトインスタンスに接続している場合、db.namespace はデータベース名に設定すべきです（SHOULD）。名前付きインスタンスに接続している場合、db.namespace は {instance_name}|{database_name} のパターンに従って、インスタンス名とデータベース名を組み合わせたものに設定すべきです（SHOULD）。
接続に現在関連付けられているデータベースは、たとえば USE <database> の実行によって、その生存期間中に変化することがあります。
計装が、追加のクエリの実行（たとえば SELECT DB_NAME()）を引き起こさずに、各クエリで接続に現在関連付けられているデータベースを取得できない場合、接続確立時に提供されたデータベースにフォールバックして使用することが推奨されます（RECOMMENDED）。
計装は、db.namespace が接続確立時に提供されたデータベースを反映しているかどうかを文書化すべきです（SHOULD）。
値は、大文字小文字の正規化を試みずに、アプリケーションから提供されたとおりに取得することが推奨されます（RECOMMENDED）。
[2] db.response.status_code: Microsoft SQL ServerはSQLSTATEを報告しません。
計装は、ステータスコードとともに返されるエラーの重大度を使って、スパンのステータスを判定すべきです（SHOULD）。重大度11以上の応答コードはエラーとして扱うべきです（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を含む）を受け付けるという理由だけでは、データベース呼び出しはバッチ操作にはなりません。
同じパラメータ化された操作をパラメータセットとともに実行するバッチ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: クエリ要約は、データベースクエリのクラスを記述するものであり、特に複雑なクエリを含むデータベース呼び出しのテレメトリーを分析する際に、グルーピングキーとして有用です。
要約は、計装フックその他の手段によって計装から利用可能な場合があります。利用可能でない場合、クエリ解析をサポートする計装は、クエリ要約の生成の節に従って要約を生成すべきです（SHOULD）。
バッチ操作については、個々の操作が同じクエリ要約を持つことがわかっている場合、そのクエリ要約の前に BATCH を付けて使用すべきです（SHOULD）。そうでない場合、db.query.summary は BATCH、またはより適切であれば他のデータベースシステム固有の用語にすべきです（SHOULD）。
[13] db.query.text: 非パラメータ化クエリテキストは、機密データを除外するサニタイズ（たとえばクエリテキスト中のすべてのリテラル値をマスクするなど）が行われていない限り、デフォルトで収集すべきではありません（SHOULD NOT）。db.query.text のサニタイズを参照してください。
パラメータ化クエリテキストはデフォルトで収集すべきです（SHOULD）（クエリパラメータの値自体はオプトインです。db.query.parameter.<key> を参照してください）。
[14] db.query.text: サニタイズについてはdb.query.text のサニタイズを参照してください。
バッチ操作については、個々の操作が同じクエリテキストを持つことがわかっている場合、そのクエリテキストを使用すべきです（SHOULD）。そうでない場合、個々のクエリテキストはすべて、セパレーター ; 、またはより適切であれば他のデータベースシステム固有のセパレーターで連結すべきです（SHOULD）。
パラメータ化クエリテキストはサニタイズすべきではありません（SHOULD NOT）。パラメータ化クエリテキストには機密データが含まれる可能性がありますが、パラメータ化クエリを使用することで、ユーザーは機密データがパラメータ値として渡されるという強い意図を示していることになり、デフォルトでクエリテキストの静的な部分を取得することによるオブザーバビリティ上の利点が、そのリスクを上回ります。
[15] db.stored_procedure.name: 操作が特定のストアドプロシージャに適用される場合。
[16] db.stored_procedure.name: 値は、大文字小文字の正規化を試みずに、アプリケーションから提供されたとおりに取得することが推奨されます（RECOMMENDED）。
バッチ操作については、個々の操作が同じストアドプロシージャ名を持つことがわかっている場合、そのストアドプロシージャ名を使用すべきです（SHOULD）。
[17] server.address: クライアント側から観測され、かつ中間者を介して通信している場合、server.address は、利用可能であれば、あらゆる中間者の背後にあるサーバーアドレスを表すべきです（SHOULD）。
[18] 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）。
[19] db.response.returned_rows: 計装がスパン終了時点で観測した、データベース操作によって返された行数。
以下の属性は、サンプリングの判断を行う上で重要な場合があり、スパン作成時に（提供する場合は）提供すべきです（SHOULD）。
error.type には、以下の既知の値の一覧があります。これらのいずれかが該当する場合、対応する値を使用しなければなりません（MUST）。それ以外の場合は、独自の値を使用してもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
_OTHER | 計装が独自の値を定義していない場合に使用するフォールバックのエラー値。 | |
Context propagation
ステータス: Development
SET CONTEXT_INFO
計装は、クエリを実行する前にスパンコンテキストの固定長部分（トレースID、スパンID、トレースフラグ、プロトコルバージョン）を注入することで、SET CONTEXT_INFOを用いてコンテキストを伝搬してもかまいません（MAY）。たとえばW3C TraceContextを使う場合、traceparentの文字列表現のみを注入すべきです（SHOULD）。コンテキスト注入はデフォルトで有効にすべきではありません（SHOULD NOT）が、計装はユーザーがオプトインできるようにしてもかまいません（MAY）。
CONTEXT_INFO の値の長さは128バイトに制限されているため、可変長のコンテキスト部分（tracestate、baggage）は注入すべきではありません（SHOULD NOT）。
コンテキストを伝搬する計装は、SQL文と同じ物理接続上で（またはそのトランザクションを再利用して）SET CONTEXT_INFO を実行しなければなりません（MUST）。
SET CONTEXT_INFO はその構文 SET CONTEXT_INFO { binary_str | @binary_var } に従いバイナリの入力を必要とし、最大サイズは128バイトであることに注意してください。
例:
traceparent が 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01 であるクエリ SELECT * FROM songs の場合:
SQL文と同じ物理接続上で以下のコマンドを実行します。
-- The binary conversion may be done by the application or the driver.
DECLARE @traceparent varbinary(55);
SET @traceparent = CAST('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01' AS varbinary(55));
SET CONTEXT_INFO @traceparent;
続いてクエリを実行します。
SELECT * FROM songs;
Metrics
Microsoft SQL Serverクライアントの計装は、データベースクライアントのメトリクスに関する全般的なセマンティック規約に従ってメトリクスを収集すべきです（SHOULD）。
db.system.name は "microsoft.sql_server" に設定しなければなりません（MUST）。