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

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

SQLデータベースクライアントの操作に関するセマンティック規約

ステータス: 特に注記のない限りStable

Spans

Status:

SQLデータベースに関するセマンティック規約は、一般的なデータベースに関するセマンティック規約がSQLデータベースにどのように適用されるかを説明します。

以下のデータベースシステム（db.system.nameで定義されている）は、SQLを主要なクエリ言語として使用することが知られています。

• actian.ingres
• cockroachdb
• derby
• firebirdsql
• h2database
• hsqldb
• ibm.db2
• mariadb
• microsoft.sql_server
• mysql
• oracle.db
• other_sql
• postgresql
• sap.maxdb
• sqlite
• trino

その他多くのデータベースシステムがSQLをサポートし、JDBCやODBCなどの汎用データベースドライバを介してアクセスできます。汎用SQLドライバに適用される計装は、SQLセマンティック規約に準拠すべきです（SHOULD）。

スパン名は、データベースのスパン名に関する全般的な命名規則に従うべきです（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]	customers; test.users
db.response.status_code		Conditionally Required If response has ended with warning or an error.	string	文字列として記録されたデータベースの応答コード。 [2]	ORA-17027; 1052; 2201B
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: データベースシステムが複数の名前空間コンポーネント（スキーマ名やデータベース名など）を持つ場合、それらはコンポーネント間の区切り文字として | を使い、最も一般的なものから最も特定的なものへと連結すべきです（SHOULD）。 欠落しているコンポーネント（およびそれに対応する区切り文字）は省略すべきです（SHOULD）。

個々のデータベースシステムに関するセマンティック規約は、そのシステムにおいて db.namespace が何を意味するかを文書化すべきです（SHOULD）。

接続に現在関連付けられているデータベースは、たとえば USE <database> の実行によって、その生存期間中に変化することがあります。

計装が、追加のクエリの実行（たとえば SELECT DATABASE()）を引き起こさずに、各クエリで接続に現在関連付けられているデータベースを取得できない場合、接続確立時に提供されたデータベースにフォールバックして使用することが推奨されます（RECOMMENDED）。

計装は、db.namespace が接続確立時に提供されたデータベースを反映しているかどうかを文書化すべきです（SHOULD）。

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

[2] db.response.status_code: SQLは、PostgreSQLなどの一部のデータベースシステムで採用されている、データベースの戻りコードとしてSQLSTATEを定義しています。 詳細はPostgreSQLのエラーコードを参照してください。

MySQL、Oracle、MS SQL Serverなどの他のシステムは、ベンダー固有のエラーコードを定義しています。データベースのSQLドライバは通常、両方のプロパティへのアクセスを提供します。 たとえばJavaでは、SQLExceptionクラスが getSQLState() メソッドと getErrorCode() メソッドでこれらを報告します。

計装は、利用可能な中で最も具体的なコードを db.response.status_code に設定すべきです（SHOULD）。

SQLSTATEより高い粒度でベンダー固有のコードを報告する（あるいはSQLSTATEを一切報告しない）データベースの非網羅的な一覧は以下のとおりです。

• DB2のSQLコード
• MariaDBのエラーコード
• Microsoft SQL Serverのエラー
• MySQLのエラーコード
• Oracleのエラーコード
• SQLiteの結果コード

これらのシステムは、db.response.status_code を既知のベンダー固有のエラーコードに設定すべきです（SHOULD）。SQLSTATEのみが利用可能な場合は、それを使用すべきです（SHOULD）。

複数のエラーコードが利用可能であり、どちらが具体的かが明確でない場合、計装は db.response.status_code を、区切り文字として / を使ってすべてのコードを連結した文字列に設定すべきです（SHOULD）。

たとえば、汎用DB計装がエラーを検出し、SQLSTATE "42000" とベンダー固有のコード 1071 の両方を持つ場合、db.response.status_code は "42000/1071" に設定すべきです。

[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）。

• db.query.summary
• db.query.text
• server.address
• server.port

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

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

Example

以下は、MySQLデータベースのスパンにおける属性の例です。