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

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

Elasticsearchクライアント操作に関するセマンティック規約

ステータス: Development

Elasticsearch に関するセマンティック規約は、データベースのセマンティック規約を拡張し、上書きします。

Spans

Status:

Elasticsearchへの呼び出しを表すスパンは、データベースクライアントのスパンに関する全般的なセマンティック規約に従います。

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

スパン名は、db.operation.name に格納されたエンドポイント識別子と、db.collection.name に格納されたインデックスを使って、全般的なデータベースのスパン名に関する規約に従うべきです（SHOULD）。

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

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

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
db.operation.name		Required	string	実行されている操作またはコマンドの名前。 [1]	search; ml.close_job; cat.aliases
http.request.method		Required	string	HTTPリクエストメソッド。 [2]	GET; POST; HEAD
url.full		Required	string	RFC3986に従ってネットワークリソースを記述する絶対URL。 [3]	https://localhost:9200/index/_search?q=user.id:kimchy
db.operation.parameter.<key>		Conditionally Required when the URL has path parameters	string	URLパス内の動的な値。 [4]	db.operation.parameter.index="test-index"; db.operation.parameter="123"
db.response.status_code		Conditionally Required If response was received.	string	Elasticsearchクラスターによって返されたHTTP応答コード。 [5]	200; 201; 429
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 [7]	int	サーバーのポート番号。 [8]	80; 8080; 443
db.collection.name		Recommended	string	クエリが実行される対象のインデックスまたはデータストリーム。 [9]	my_index; index1, index2
db.namespace		Recommended	string	クライアントが接続するElasticsearchクラスターの名前。 [10]	customers; test.users
db.operation.batch.size		Recommended	int	バッチ操作に含まれるデータベース操作の数。 [11]	2; 3; 4
db.query.text		Recommended [12]	string	検索系クエリのリクエストボディを、JSON文字列として表したもの。 [13]	"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"
elasticsearch.node.name		Recommended	string	リクエストがルーティングされたノード・インスタンスの、人間が読める識別子を表す。 [14]	instance-0000000001
server.address		Recommended	string	データベースホストの名前。 [15]	example.com; 10.1.2.80; /tmp/my.sock

[1] db.operation.name: db.operation.name は、リクエストで提供されたエンドポイント識別子と一致すべきです（SHOULD）（Elasticsearchスキーマを参照）。 バッチ操作については、個々の操作が同じ操作名を持つことがわかっている場合、その操作名の前に bulk を付けて使用すべきです（SHOULD）。そうでない場合、db.operation.name は bulk にすべきです（SHOULD）。

[2] http.request.method: HTTPリクエストメソッドの値は、計装に「既知」であるべきです（SHOULD）。 デフォルトでは、この規約はRFC9110に列挙されているメソッド、RFC5789で定義されたPATCHメソッド、httpbis-safe-method-w-bodyで定義されたQUERYメソッドを「既知の」メソッドとして定義します。

HTTPリクエストメソッドが計装に既知でない場合、http.request.method 属性を _OTHER に設定しなければなりません（MUST）。

HTTP計装が有効なHTTPリクエストメソッドを _OTHER に変換してしまう可能性がある場合、既知のHTTPメソッドの一覧を上書きする方法を提供しなければなりません（MUST）。 この上書きが環境変数を介して行われる場合、その環境変数は OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS という名前でなければならず（MUST）、大文字小文字を区別する既知のHTTPメソッドをカンマ区切りのリストとしてサポートしなければなりません（MUST）。

この上書きが宣言的設定を介して行われる場合、.instrumentation/development.general.http.client や .instrumentation/development.general.http.server の下にある known_methods プロパティ（最小要素数0の、大文字小文字を区別する文字列の配列）でその一覧を設定可能にしなければなりません（MUST）。

いずれの場合も、この一覧は既知のメソッドのデフォルトの完全な上書きでなければならず（MUST）、デフォルトに追加する既知のメソッドの一覧ではありません。

HTTPメソッド名は大文字小文字を区別し、http.request.method 属性の値は既知のHTTPメソッド名に正確に一致しなければなりません（MUST）。 HTTPメソッドを大文字小文字を区別しないものとして扱う特定のWebフレームワーク向けの計装は、正規化された等価な値を設定すべきです（SHOULD）。 そのようなトレーシング計装は、http.request.method_original にも元の値を設定しなければなりません（MUST）。

[3] url.full: ネットワーク呼び出しの場合、URLは通常 scheme://host[:port][path][?query][#fragment] の形式を取ります。フラグメントはHTTPで送信されませんが、既知であれば、それでも含めるべきです（SHOULD）。

url.full は、https://username:password@www.example.com/ の形式でURL経由で渡される資格情報を含んではなりません（MUST NOT）。 そのような場合、ユーザー名とパスワードは伏字にすべきであり（SHOULD）、属性の値は https://REDACTED:REDACTED@www.example.com/ にすべきです（SHOULD）。

url.full は、利用可能な（または再構築できる）場合、絶対URLを捉えるべきです（SHOULD）。

url.full に含まれる機密情報は、計装がそれを識別できる場合、除去されるべきです（SHOULD）。

次のキーに対応するクエリ文字列の値は、デフォルトで伏字にされ、値 REDACTED に置き換えられるべきです（SHOULD）。

• X-Amz-Signature
• X-Amz-Credential
• X-Amz-Security-Token
• sig
• X-Goog-Signature

この一覧は今後変更される可能性があります。

クエリパラメーターのキーと機密情報の一覧との照合は、大文字小文字を区別すべきです（SHOULD）。

計装は、宣言的設定を介してこの一覧を上書きする方法を提供してもかまいません（MAY）。 その場合、.instrumentation/development.general.sanitization.url の下にある sensitive_query_parameters プロパティ（最小要素数0の、大文字小文字を区別する文字列の配列）を使うべきです（SHOULD）。 この一覧は、デフォルトの機密なクエリパラメーターキーの完全な上書きであり、デフォルトに追加するキーの一覧ではありません。

クエリ文字列の値が伏字にされる場合でも、クエリ文字列のキーは保持されるべきです（SHOULD）。例えば https://www.example.com/path?color=blue&sig=REDACTED のようになります。

[4] db.operation.parameter.<key>: 多くのElasticsearchのURLパスは動的な値を許容します。これらは db.operation.parameter.<key> という形式でスパン属性に記録すべきです（SHOULD）。ここで <key> はパスパラメータ名です。実装は、パスパラメータの値をその名前に対応させるために、Elasticsearchスキーマを参照すべきです（SHOULD）。

[5] db.response.status_code: 4xxおよび5xx範囲のHTTP応答コードはエラーとみなすべきです（SHOULD）。

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

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

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

[9] db.collection.name: クエリは複数のインデックスまたはデータストリームを対象にすることがあり、その場合はカンマ区切りのリストにすべきです（SHOULD）。クエリが特定のインデックスを対象としない場合、このフィールドは設定してはなりません（MUST NOT）。

[10] db.namespace: Elastic Cloudデプロイメントと通信する場合、これは「X-Found-Handling-Cluster」HTTP応答ヘッダーから収集すべきです。

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

[12] db.query.text: 検索系クエリについては、機密情報を除外するサニタイズが行われている場合にのみ、デフォルトで収集すべきです（SHOULD）。

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

[14] elasticsearch.node.name: Elastic Cloudデプロイメントと通信する場合、これは「X-Found-Handling-Instance」HTTP応答ヘッダーから収集すべきです。

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

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

• db.collection.name
• db.namespace
• db.operation.name
• db.query.text
• http.request.method
• server.address
• server.port
• url.full

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

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

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

Value	Description	Stability
_OTHER	計装が事前に知らないHTTPメソッド。
CONNECT	CONNECTメソッド。
DELETE	DELETEメソッド。
GET	GETメソッド。
HEAD	HEADメソッド。
OPTIONS	OPTIONSメソッド。
PATCH	PATCHメソッド。
POST	POSTメソッド。
PUT	PUTメソッド。
QUERY	QUERYメソッド。
TRACE	TRACEメソッド。

Example

Metrics

Elasticsearchクライアントの計装は、全般的なデータベースクライアントのメトリクスに関するセマンティック規約に従ってメトリクスを収集すべきです（SHOULD）。

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