Semantic Conventions for Elasticsearch
This document defines semantic conventions to apply when creating a span for requests to Elasticsearch.
The span name SHOULD be of the format
The elasticsearch endpoint identifier is used instead of the url path in order to reduce the cardinality of the span
name, as the path could contain dynamic values. The endpoint id is the
name field in the
If the endpoint id is not available, the span name SHOULD be the
URL path parts
Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format
<key> is the url path part name. The implementation SHOULD
reference the elasticsearch schema
in order to map the path part values to their names.
|string||A dynamic value in the url path.||Conditionally Required: |
: when the url has dynamic values
db.system MUST be set to
|string||The endpoint identifier for the request. ||Required|
|string||The request body for a search-type query, as a json string.||Recommended: |
|string||HTTP request method. ||Required|
|string||Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known.||See below|
|int||Logical server port number||Recommended|
|string||Absolute URL describing a network resource according to RFC3986 ||Required|
: When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of
db.statement just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted.
: Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information.
If the HTTP request method is not known to instrumentation, it MUST set the
http.request.method attribute to
_OTHER and, except if reporting a metric, MUST
set the exact method received in the request line as value of the
If the HTTP instrumentation could end up converting valid HTTP request methods to
_OTHER, then it MUST provide a way to override
the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named
OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods
(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults).
HTTP method names are case-sensitive and
http.request.method attribute value MUST match a known HTTP method name exactly.
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set
http.request.method_original to the original value.
: 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:firstname.lastname@example.org/. In such case username and password should be redacted and attribute’s value should be
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.