Semantic conventions for Elasticsearch client operations

Status: Development

• Spans
  • Example
• Metrics

The Semantic Conventions for Elasticsearch extend and override the Database Semantic Conventions.

Spans

Status:

Spans representing calls to Elasticsearch adhere to the general Semantic Conventions for Database Client Spans.

Span name SHOULD follow the general database span name convention with the endpoint identifier stored in db.operation.name, and the index stored in db.collection.name.

Span kind SHOULD be CLIENT.

Span status SHOULD follow the Recording Errors document.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
db.operation.name		Required	string	The name of the operation or command being executed. [1]	search; ml.close_job; cat.aliases
db.system.name		Required	string	The database management system (DBMS) product as identified by the client instrumentation. [2]	elasticsearch
http.request.method		Required	string	HTTP request method. [3]	GET; POST; HEAD (see more)
url.full		Required	string	Absolute URL describing a network resource according to RFC3986 [4]	https://localhost:9200/index/_search?q=user.id:kimchy
db.operation.parameter.<key>		Conditionally Required when the URL has path parameters	string	A dynamic value in the URL path. [5]	db.operation.parameter.index="test-index"; db.operation.parameter="123"
db.response.status_code		Conditionally Required If response was received.	string	The HTTP response code returned by the Elasticsearch cluster. [6]	200; 201; 429
error.type		Conditionally Required If and only if the operation failed.	string	Describes a class of error the operation ended with. [7]	timeout; java.net.UnknownHostException; server_certificate_invalid; 500
server.port		Conditionally Required [8]	int	Server port number. [9]	80; 8080; 443
db.collection.name		Recommended	string	The index or data stream against which the query is executed. [10]	my_index; index1, index2
db.namespace		Recommended	string	The name of the Elasticsearch cluster which the client connects to. [11]	customers; test.users
db.operation.batch.size		Recommended	int	The number of database operations included in a batch operation. [12]	2; 3; 4
db.query.text		Recommended [13]	string	The request body for a search-type query, as a JSON string. [14]	"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"
elasticsearch.node.name		Recommended	string	Represents the human-readable identifier of the node/instance to which a request was routed. [15]	instance-0000000001
server.address		Recommended	string	The database address specified in the client configuration. [16]	example.com; 10.1.2.80; /tmp/my.sock

[1] db.operation.name: The db.operation.name SHOULD match the endpoint identifier provided in the request (see the Elasticsearch schema). For batch operations, if the individual operations would all have the same db.operation.name when executed as non-batch operations, then that operation name SHOULD be used prepended by bulk . Otherwise, db.operation.name SHOULD be bulk.

[2] db.system.name: MUST be set to "elasticsearch".

[3] http.request.method: HTTP request method value SHOULD be “known” to the instrumentation. By default, this convention defines “known” methods as the ones listed in RFC9110, the PATCH method defined in RFC5789 and the QUERY method defined in httpbis-safe-method-w-body.

If the HTTP request method is not known to instrumentation, it MUST set the http.request.method attribute to _OTHER.

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.

If this override is done via declarative configuration, then the list MUST be configurable via the known_methods property (an array of case-sensitive strings with minimum items 0) under .instrumentation/development.general.http.client and/or .instrumentation/development.general.http.server.

In either case, this list MUST be a full override of the default known methods, 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.

[4] url.full: 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).

Sensitive content provided in url.full SHOULD be scrubbed when instrumentations can identify it.

Query string values for the following keys SHOULD be redacted by default and replaced by the value REDACTED:

• X-Amz-Signature
• X-Amz-Credential
• X-Amz-Security-Token
• AWSAccessKeyId
• Signature
• sig
• X-Goog-Signature

Several of these keys are used by more than one service or signing scheme. Each link points to one representative usage rather than an exhaustive list, and does not narrow the scope of the key to the linked service or signing scheme.

This list is subject to change over time.

Matching of query parameter keys against the sensitive list SHOULD be case-sensitive.

Instrumentation MAY provide a way to override this list via declarative configuration. If so, it SHOULD use the sensitive_query_parameters property (an array of case-sensitive strings with minimum items 0) under .instrumentation/development.general.sanitization.url. This list is a full override of the default sensitive query parameter keys, it is not a list of keys in addition to the defaults.

When a query string value is redacted, the query string key SHOULD still be preserved, e.g. https://www.example.com/path?color=blue&sig=REDACTED.

[5] db.operation.parameter.<key>: Many Elasticsearch URL paths allow dynamic values. These SHOULD be recorded in span attributes in the format db.operation.parameter.<key>, where <key> is the path parameter name. The implementation SHOULD reference the Elasticsearch schema in order to map the path parameter values to their names.

[6] db.response.status_code: HTTP response codes in the 4xx and 5xx range SHOULD be considered errors.

[7] error.type: The error.type SHOULD match the db.response.status_code returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. Instrumentations SHOULD document how error.type is populated.

[8] server.port: If server.address is set and the client is configured with a single database server endpoint that uses a non-default port.

[9] server.port: server.port SHOULD reflect the database port specified in the client configuration. It SHOULD NOT be derived from the server selected for an operation.

[10] db.collection.name: The query may target multiple indexes or data streams, in which case it SHOULD be a comma separated list of those. If the query doesn’t target a specific index, this field MUST NOT be set.

[11] db.namespace: When communicating with an Elastic Cloud deployment, this should be collected from the “X-Found-Handling-Cluster” HTTP response header.

[12] db.operation.batch.size: Except for empty batch requests described below, a batch operation contains two or more database operations explicitly submitted as separate operations in a single client call, protocol message, or database command.

Requests to batch APIs that contain only one operation SHOULD be modeled as single operations, not as batch operations.

A database call is not a batch operation solely because one operation accepts multiple operands, such as keys, rows, documents, points, or other data elements, including Redis MGET with multiple keys.

In batch APIs that execute the same parameterized operation with parameter sets, each parameter set represents one database operation for determining whether the request is a batch operation. Requests with only one parameter set SHOULD be modeled as single operations, not as batch operations.

db.operation.batch.size SHOULD be set to the number of operations in the batch. It SHOULD NOT be set for non-batch operations.

A request to execute a batch operation with no operations SHOULD also be treated as a batch operation, and db.operation.batch.size SHOULD be set to 0.

[13] db.query.text: Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information.

[14] db.query.text:

For sanitization see Sanitization of db.query.text. For batch operations, if the individual operations would all have the same db.query.text when executed as non-batch operations, then that query text SHOULD be used. Otherwise, all of the individual query texts SHOULD be concatenated with separator ; or some other database system specific separator if more applicable. Parameterized query text SHOULD NOT be sanitized. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.

[15] elasticsearch.node.name: When communicating with an Elastic Cloud deployment, this should be collected from the “X-Found-Handling-Instance” HTTP response header.

[16] server.address: Instrumentation SHOULD set server.address to the database address specified in the client configuration. It SHOULD NOT derive the value from the server selected for an operation.

See Database server address for guidance and examples.

The following attributes can be important for making sampling decisions and SHOULD be provided at span creation time (if provided at all):

• db.collection.name
• db.namespace
• db.operation.name
• db.query.text
• db.system.name
• http.request.method
• server.address
• server.port
• url.full

http.request.method has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
_OTHER	Any HTTP method that the instrumentation has no prior knowledge of.
CONNECT	CONNECT method.
DELETE	DELETE method.
GET	GET method.
HEAD	HEAD method.
OPTIONS	OPTIONS method.
PATCH	PATCH method.
POST	POST method.
PUT	PUT method.
QUERY	QUERY method.
TRACE	TRACE method.

Example

Metrics

Elasticsearch client instrumentations SHOULD collect metrics according to the general Semantic Conventions for Database Client Metrics.

db.system.name MUST be set to "elasticsearch".