diff --git a/semantic_conventions/trace/database.yaml b/semantic_conventions/trace/database.yaml index e89f5eadf3c..7f3375fe6f4 100644 --- a/semantic_conventions/trace/database.yaml +++ b/semantic_conventions/trace/database.yaml @@ -385,6 +385,47 @@ groups: The collection being accessed within the database stated in `db.name`. examples: [ 'customers', 'products' ] + - id: db.elasticsearch + prefix: db.elasticsearch + type: span + extends: db + brief: > + Call-level attributes for Elasticsearch + attributes: + - id: doc_id + type: string + requirement_level: + conditionally_required: when the request targets a specific document by id + tag: call-level-tech-specific-elasticsearch + brief: > + The document that the request targets. + examples: [ '123', '456' ] + - id: url.query + type: string + requirement_level: + conditionally_required: when query params are provided as part of the request + tag: call-level-tech-specific + brief: > + The query params of the request, as a json string. + examples: [ '"{\"q\":\"test\"}", "{\"refresh\":true}"' ] + - id: target + type: string + requirement_level: + conditionally_required: when a specific index or data stream is targeted by the request + tag: call-level-tech-specific + brief: > + The name of the data stream or index that is targeted. + examples: [ 'users' ] + - id: url.path + type: string + requirement_level: required + tag: call-level-tech-specific + brief: > + The path of the request, including the target and exact document id. + examples: [ '/test-index/_search', '/test-index/_doc/123' ] + - ref: http.method + requirement_level: required + - id: db.sql prefix: 'db.sql' type: span @@ -517,3 +558,4 @@ groups: - include: 'db.mongodb' - include: 'db.sql' - include: 'db.cosmosdb' + - include: 'db.elasticsearch' diff --git a/specification/trace/semantic_conventions/README.md b/specification/trace/semantic_conventions/README.md index 78656e96710..813c81969ea 100644 --- a/specification/trace/semantic_conventions/README.md +++ b/specification/trace/semantic_conventions/README.md @@ -29,6 +29,7 @@ The following library-specific semantic conventions are defined: * [AWS Lambda](instrumentation/aws-lambda.md): For AWS Lambda spans. * [AWS SDK](instrumentation/aws-sdk.md): For AWS SDK spans. +* [Elasticsearch](instrumentation/elasticsearch.md): For Elasticsearch spans. * [GraphQL](instrumentation/graphql.md): For GraphQL spans. Apart from semantic conventions for traces and [metrics](../../metrics/semantic_conventions/README.md), diff --git a/specification/trace/semantic_conventions/instrumentation/elasticsearch.md b/specification/trace/semantic_conventions/instrumentation/elasticsearch.md new file mode 100644 index 00000000000..f690bd2490e --- /dev/null +++ b/specification/trace/semantic_conventions/instrumentation/elasticsearch.md @@ -0,0 +1,31 @@ +# Semantic conventions for Elasticsearch + +**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. + +## Span Name + +The **span name** SHOULD be of the format ` `. + +The elasticsearch url is modified with placeholders in order to reduce the cardinality of the span name. When the url +contains a document id, it SHOULD be replaced by the identifier `{id}`. When the url contains a target data stream or +index, it SHOULD be replaced by `{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 url, as in `POST /_search`. + +### Span attributes + + +| Attribute | Type | Description | Examples | Requirement Level | +|----------------------------|---|----------------------------------------------------------------------|---------------------------------------------------------|------------------------| +| `db.elasticsearch.doc_id` | string | The document that the request targets, specified in the path. | `'123'` | Conditionally Required | +| `db.elasticsearch.target` | string | The name of the data stream or index that is targeted. | `'users'` | Conditionally Required | +| `db.elasticsearch.url.path` | string | The exact path of the request, including the target and document id. | `'/test-index/_doc/123'` | Required | +| `db.elasticsearch.url.query` | string | The query params of the request, as a json string. | `'"{\"q\":\"test\"}", "{\"refresh\":true}"'` | Conditionally Required | +| `db.statement` | string | The request body, as a json string. [1] | `"{\"name\":\"TestUser\",\"password\":\"top_secret\"}"` | Conditionally Required | +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | + +**[1]:** The value may be sanitized to exclude sensitive information. +