Add semantic conventions for Elasticsearch client instrumentation

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'

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),

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 `<http.method> <db.elasticsearch.url *with placeholders*>`.
+
+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
+
+<!-- semconv elasticsearch -->
+| 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.
+<!-- endsemconv -->