diff --git a/semantic_conventions/trace/database.yaml b/semantic_conventions/trace/database.yaml index a7b94df51b..8d080b90af 100644 --- a/semantic_conventions/trace/database.yaml +++ b/semantic_conventions/trace/database.yaml @@ -405,23 +405,19 @@ groups: brief: > The name of the data stream or index that is targeted. examples: [ 'users' ] - - ref: url.query - requirement_level: - conditionally_required: when query params are provided as part of the request - brief: > - The query params of the request, as a json string. - examples: [ '"{\"q\":\"test\"}", "{\"refresh\":true}"' ] - - ref: url.path + - ref: url.full requirement_level: required - brief: > - The path of the request, including the target and exact document id. - examples: [ '/test-index/_search', '/test-index/_doc/123' ] + examples: [ 'https://localhost:9200/index/_search?q=user.id:kimchy' ] - ref: db.statement requirement_level: - conditionally_required: when there is a request body - brief: The request body, as a json string. + conditionally_required: when a search-type query is executed + brief: The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. note: The value may be sanitized to exclude sensitive information. examples: [ '"{\"name\":\"TestUser\",\"password\":\"top_secret\"}"' ] + - ref: server.address + requirement_level: recommended + - ref: server.port + requirement_level: recommended - ref: http.request.method requirement_level: required diff --git a/specification/trace/semantic_conventions/instrumentation/elasticsearch.md b/specification/trace/semantic_conventions/instrumentation/elasticsearch.md index 4e9d6607d8..bf2248dc7d 100644 --- a/specification/trace/semantic_conventions/instrumentation/elasticsearch.md +++ b/specification/trace/semantic_conventions/instrumentation/elasticsearch.md @@ -3,17 +3,18 @@ **Status**: [Experimental](../../../document-status.md) This document defines semantic conventions to apply when instrumenting requests to Elasticsearch. They map Elasticsearch -requests to attributes on a Span. +requests to attributes on a Span. Note that there may also be an http span created in addition to the Elasticsearch +span. ## Span Name The **span name** SHOULD be of the format ` `. -The elasticsearch url path is modified with placeholders in order to reduce the cardinality of the span name. When the -path contains a document id, it SHOULD be replaced by the identifier `{id}`. When the path contains a target data stream -or index, it SHOULD be replaced by `{target}`. +The elasticsearch url path is used with placeholders in order to reduce the cardinality of the span name. When the +path contains a document id, it SHOULD be represented as the identifier `{id}`. When the path contains a target data stream +or index, it SHOULD be represented as `{target}`. For example, a request to `/test-index/_doc/123` should have the span name `GET /{target}/_doc/{id}`. -When there is no target or document id, the span name will contain the exact path, as in `POST /_search`. +When there is no target or document id, the span name contains the exact path, as in `POST /_search`. ### Span attributes @@ -22,10 +23,11 @@ When there is no target or document id, the span name will contain the exact pat |---|---|---|---|---| | `db.elasticsearch.doc_id` | string | The document that the request targets. | `123`; `456` | Conditionally Required: [1] | | `db.elasticsearch.target` | string | The name of the data stream or index that is targeted. | `users` | Conditionally Required: [2] | -| [`db.statement`](../database.md) | string | The request body, as a json string. [3] | `"{\"name\":\"TestUser\",\"password\":\"top_secret\"}"` | Conditionally Required: when there is a request body | +| [`db.statement`](../database.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. [3] | `"{\"name\":\"TestUser\",\"password\":\"top_secret\"}"` | Conditionally Required: when a search-type query is executed | | `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| `url.path` | string | The path of the request, including the target and exact document id. [4] | `/test-index/_search`; `/test-index/_doc/123` | Required | -| `url.query` | string | The query params of the request, as a json string. [5] | `"{\"q\":\"test\"}", "{\"refresh\":true}"` | Conditionally Required: [6] | +| [`server.address`](../span-general.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | See below | +| [`server.port`](../span-general.md) | int | Logical server port number | `80`; `8080`; `443` | Recommended | +| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [4] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required | **[1]:** when the request targets a specific document by id @@ -33,9 +35,7 @@ When there is no target or document id, the span name will contain the exact pat **[3]:** The value may be sanitized to exclude sensitive information. -**[4]:** When missing, the value is assumed to be `/` - -**[5]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. - -**[6]:** when query params are provided as part of the request +**[4]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. +`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`. +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes.