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. 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