From 19a91e5f232e971dad196b5b30a060b6904e86ea Mon Sep 17 00:00:00 2001 From: Laura Trotta Date: Thu, 20 Aug 2026 12:29:00 +0200 Subject: [PATCH 1/2] use new convention for index metric --- .../instrumentation/OpenTelemetryForElasticsearch.java | 2 +- .../instrumentation/OpenTelemetryForElasticsearchTest.java | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/java-client/src/main/java/co/elastic/clients/transport/instrumentation/OpenTelemetryForElasticsearch.java b/java-client/src/main/java/co/elastic/clients/transport/instrumentation/OpenTelemetryForElasticsearch.java index cc42e7a812..e9f300466d 100644 --- a/java-client/src/main/java/co/elastic/clients/transport/instrumentation/OpenTelemetryForElasticsearch.java +++ b/java-client/src/main/java/co/elastic/clients/transport/instrumentation/OpenTelemetryForElasticsearch.java @@ -83,7 +83,7 @@ public class OpenTelemetryForElasticsearch implements Instrumentation { // Caching attributes keys to avoid unnecessary memory allocation private static final Map> attributesKeyCache = new ConcurrentHashMap<>(); - AttributeKeyTemplate PATH_PART_PREFIX = AttributeKeyTemplate.stringKeyTemplate("db.elasticsearch.path_parts"); + AttributeKeyTemplate PATH_PART_PREFIX = AttributeKeyTemplate.stringKeyTemplate("db.operation.parameter"); // these reflect the config options in the OTel Java agent private static final boolean INSTRUMENTATION_ENABLED = Boolean.parseBoolean( diff --git a/java-client/src/test/java/co/elastic/clients/transport/instrumentation/OpenTelemetryForElasticsearchTest.java b/java-client/src/test/java/co/elastic/clients/transport/instrumentation/OpenTelemetryForElasticsearchTest.java index 1faea82b6d..6716c02b6f 100644 --- a/java-client/src/test/java/co/elastic/clients/transport/instrumentation/OpenTelemetryForElasticsearchTest.java +++ b/java-client/src/test/java/co/elastic/clients/transport/instrumentation/OpenTelemetryForElasticsearchTest.java @@ -197,7 +197,7 @@ public void testGetRequest() throws IOException, InterruptedException { Assertions.assertEquals(httpServer.getAddress().getPort(), span.getAttributes().get(ServerAttributes.SERVER_PORT)); // Path parts - Assertions.assertEquals(DOC_ID, span.getAttributes().get(AttributeKey.stringKey("db.elasticsearch.path_parts.id"))); + Assertions.assertEquals(DOC_ID, span.getAttributes().get(AttributeKey.stringKey("db.operation.parameter.id"))); } @Test From 1c51112912d9b7ca7cbae56a4e212b4232c83642 Mon Sep 17 00:00:00 2001 From: Laura Trotta Date: Thu, 20 Aug 2026 17:07:56 +0200 Subject: [PATCH 2/2] update otel docs --- docs/reference/setup/opentelemetry.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/reference/setup/opentelemetry.md b/docs/reference/setup/opentelemetry.md index 898c5cd606..1db4156dfa 100644 --- a/docs/reference/setup/opentelemetry.md +++ b/docs/reference/setup/opentelemetry.md @@ -89,6 +89,27 @@ Per default, the built-in OpenTelemetry instrumentation does not capture request | Environment Variable | `OTEL_INSTRUMENTATION_ELASTICSEARCH_CAPTURE_SEARCH_QUERY` | + +### Database semantic conventions stability opt-in [_database_semconv_opt_in] + +The [OpenTelemetry Semantic Conventions for {{es}}](https://opentelemetry.io/docs/specs/semconv/database/elasticsearch/) renamed the request path parameter attributes from `db.elasticsearch.path_parts.` to `db.operation.parameter.`. To avoid breaking existing dashboards and alerts, the client keeps emitting the deprecated `db.elasticsearch.path_parts.` attributes by default. Following the OpenTelemetry `otel.semconv-stability.opt-in` mechanism, you can opt in to the new attributes: + +* `database`: emit the new `db.operation.parameter.` attributes. +* `database/dup`: emit both the new `db.operation.parameter.` and the deprecated `db.elasticsearch.path_parts.` attributes. + +**Default:** neither (only the deprecated `db.elasticsearch.path_parts.` attributes are emitted) + +Note that in this client the `otel.semconv-stability.opt-in` flag only affects the path parameter attributes. The other database attributes emitted by the client (`db.system.name`, `db.operation.name`, and `db.query.text`) already follow the stable Semantic Conventions since version 9.2 and are emitted regardless of this setting. + +::::{warning} +The `db.elasticsearch.path_parts.` attribute name is deprecated. It remains the default in the 9.4 and 9.5 releases for backwards compatibility, and will be dropped in 9.6, after which the client will always emit `db.operation.parameter.`. +:::: + +| | | +| --- | --- | +| Java System Property | `otel.semconv-stability.opt-in` | +| Environment Variable | `OTEL_SEMCONV_STABILITY_OPT_IN` | + ## Overhead [_overhead] The OpenTelemetry instrumentation (as any other monitoring approach) may come with a little overhead on CPU, memory and/or latency. The overhead may only occur when the instrumentation is enabled (default) and an OpenTelemetry SDK (or an OpenTelemetry Agent) is active in the target application. In case that either the instrumentation is disabled or no OpenTelemetry SDK (or OpenTelemetry Agent) is active with the target application, there is no monitoring overhead expected when using the client.