> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/db/elasticsearch/ # Elasticsearchクライアント操作に関するセマンティック規約 **ステータス**: [Development][DocumentStatus] [Elasticsearch](https://www.elastic.co/) に関するセマンティック規約は、[データベースのセマンティック規約](/works/otel-specs-ja/semconv/db/)を拡張し、上書きします。 ## Spans **Status:** ![Development](https://img.shields.io/badge/-development-blue) Elasticsearchへの呼び出しを表すスパンは、[データベースクライアントのスパンに関する全般的なセマンティック規約](/works/otel-specs-ja/semconv/db/database-spans/)に従います。 `db.system.name` は `"elasticsearch"` に設定しなければならず（MUST）、**スパン作成時**に提供すべきです（SHOULD）。 **スパン名**は、`db.operation.name` に格納されたエンドポイント識別子と、`db.collection.name` に格納されたインデックスを使って、全般的な[データベースのスパン名に関する規約](/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] | `search`; `ml.close_job`; `cat.aliases` | | [`http.request.method`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | HTTPリクエストメソッド。 [2] | `GET`; `POST`; `HEAD` | | [`url.full`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/url/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | [RFC3986](https://www.rfc-editor.org/rfc/rfc3986)に従ってネットワークリソースを記述する絶対URL。 [3] | `https://localhost:9200/index/_search?q=user.id:kimchy` | | [`db.operation.parameter.`](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` when the URL has path parameters | string | URLパス内の動的な値。 [4] | `db.operation.parameter.index="test-index"`; `db.operation.parameter="123"` | | [`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 | Elasticsearchクラスターによって返されたHTTP応答コード。 [5] | `200`; `201`; `429` | | [`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` [7] | int | サーバーのポート番号。 [8] | `80`; `8080`; `443` | | [`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) | `Recommended` | string | クエリが実行される対象のインデックスまたはデータストリーム。 [9] | `my_index`; `index1, index2` | | [`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) | `Recommended` | string | クライアントが接続するElasticsearchクラスターの名前。 [10] | `customers`; `test.users` | | [`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 | バッチ操作に含まれるデータベース操作の数。 [11] | `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` [12] | string | [検索系クエリ](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html)のリクエストボディを、JSON文字列として表したもの。 [13] | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | | [`elasticsearch.node.name`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/elasticsearch/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | リクエストがルーティングされたノード・インスタンスの、人間が読める識別子を表す。 [14] | `instance-0000000001` | | [`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 | データベースホストの名前。 [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | **[1] `db.operation.name`:** `db.operation.name` は、リクエストで提供されたエンドポイント識別子と一致すべきです（SHOULD）（[Elasticsearchスキーマ](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json)を参照）。 バッチ操作については、個々の操作が同じ操作名を持つことがわかっている場合、その操作名の前に `bulk ` を付けて使用すべきです（SHOULD）。そうでない場合、`db.operation.name` は `bulk` にすべきです（SHOULD）。 **[2] `http.request.method`:** HTTPリクエストメソッドの値は、計装に「既知」であるべきです（SHOULD）。 デフォルトでは、この規約は[RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)に列挙されているメソッド、[RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html)で定義されたPATCHメソッド、[httpbis-safe-method-w-body](https://datatracker.ietf.org/doc/draft-ietf-httpbis-safe-method-w-body/?include_text=1)で定義されたQUERYメソッドを「既知の」メソッドとして定義します。 HTTPリクエストメソッドが計装に既知でない場合、`http.request.method` 属性を `_OTHER` に設定しなければなりません（MUST）。 HTTP計装が有効なHTTPリクエストメソッドを `_OTHER` に変換してしまう可能性がある場合、既知のHTTPメソッドの一覧を上書きする方法を提供しなければなりません（MUST）。 この上書きが環境変数を介して行われる場合、その環境変数は OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS という名前でなければならず（MUST）、大文字小文字を区別する既知のHTTPメソッドをカンマ区切りのリストとしてサポートしなければなりません（MUST）。 ![Development](https://img.shields.io/badge/-development-blue) この上書きが宣言的設定を介して行われる場合、`.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）。 ![Development](https://img.shields.io/badge/-development-blue) 次のキーに対応するクエリ文字列の値は、デフォルトで伏字にされ、値 `REDACTED` に置き換えられるべきです（SHOULD）。 * [`X-Amz-Signature`](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-authentication-methods.html) * [`X-Amz-Credential`](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-authentication-methods.html) * [`X-Amz-Security-Token`](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-authentication-methods.html) * [`sig`](https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token) * [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls) この一覧は今後変更される可能性があります。 クエリパラメーターのキーと機密情報の一覧との照合は、大文字小文字を区別すべきです（SHOULD）。 ![Development](https://img.shields.io/badge/-development-blue) 計装は、宣言的設定を介してこの一覧を上書きする方法を提供してもかまいません（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.`:** 多くのElasticsearchのURLパスは動的な値を許容します。これらは `db.operation.parameter.` という形式でスパン属性に記録すべきです（SHOULD）。ここで `` はパスパラメータ名です。実装は、パスパラメータの値をその名前に対応させるために、[Elasticsearchスキーマ](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json)を参照すべきです（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`](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）。 **[12] `db.query.text`:** 検索系クエリについては、機密情報を除外するサニタイズが行われている場合にのみ、デフォルトで収集すべきです（SHOULD）。 **[13] `db.query.text`:** サニタイズについては[`db.query.text` のサニタイズ](/works/otel-specs-ja/semconv/db/database-spans/#sanitization-of-dbquerytext)を参照してください。 バッチ操作については、個々の操作が同じクエリテキストを持つことがわかっている場合、そのクエリテキストを使用すべきです（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`](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/) * [`db.query.text`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) * [`http.request.method`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/) * [`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/) * [`url.full`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/url/) --- `error.type` には、以下の既知の値の一覧があります。これらのいずれかが該当する場合、対応する値を使用しなければなりません（MUST）。それ以外の場合は、独自の値を使用してもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | 計装が独自の値を定義していない場合に使用するフォールバックのエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | --- `http.request.method` には、以下の既知の値の一覧があります。これらのいずれかが該当する場合、対応する値を使用しなければなりません（MUST）。それ以外の場合は、独自の値を使用してもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | 計装が事前に知らないHTTPメソッド。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `CONNECT` | CONNECTメソッド。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `DELETE` | DELETEメソッド。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `GET` | GETメソッド。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `HEAD` | HEADメソッド。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `OPTIONS` | OPTIONSメソッド。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `PATCH` | PATCHメソッド。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `POST` | POSTメソッド。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `PUT` | PUTメソッド。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `QUERY` | QUERYメソッド。 | ![Development](https://img.shields.io/badge/-development-blue) | | `TRACE` | TRACEメソッド。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ### Example | Key | Value | | :----------------------------- | :----------------------------------------------------------------------------------- | | Span name | `"search my-index"` | | `db.system.name` | `"elasticsearch"` | | `server.address` | `"elasticsearch.mydomain.com"` | | `server.port` | `9200` | | `http.request.method` | `"GET"` | | `db.query.text` | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | | `db.operation.name` | `"search"` | | `db.collection.name` | `"my-index"` | | `url.full` | `"https://elasticsearch.mydomain.com:9200/my-index-000001/_search?from=40&size=20"` | | `db.namespace` | `"my-cluster"` | | `elasticsearch.node.name` | `"instance-0000000001"` | | `db.operation.parameter.index` | `"my-index-000001"` | ## Metrics Elasticsearchクライアントの計装は、全般的な[データベースクライアントのメトリクスに関するセマンティック規約](/works/otel-specs-ja/semconv/db/database-metrics/)に従ってメトリクスを収集すべきです（SHOULD）。 `db.system.name` は `"elasticsearch"` に設定しなければなりません（MUST）。 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status