Added an example to the docs of using custom OTel instance

Signed-off-by: Alexander Wert <alexander.wert@elastic.co>
elastic · Sep 6, 2023 · 972f13c · 972f13c
1 parent de90eb3
commit 972f13c
Show file tree

Hide file tree

Showing 2 changed files with 49 additions and 2 deletions.
diff --git a/docs/setup/open-telemetry.asciidoc b/docs/setup/open-telemetry.asciidoc
@@ -19,6 +19,18 @@ image::../images/otel-waterfall-retries.jpg[alt="Distributed trace with request
 
 The first node is unavailable and results in an HTTP error, while the retry to the second node succeeds. Both HTTP requests are subsumed by the logical Elasticsearch request span (in blue).
 
+[[opentelemetry-setup]]
+==== Setup the OpenTelemetry instrumentation
+When using the https://opentelemetry.io/docs/instrumentation/java/manual[OpenTelemetry Java SDK manually] or using the https://opentelemetry.io/docs/instrumentation/java/automatic/[OpenTelemetry Java Agent], the Java API Client's OpenTelemetry instrumentation is enabled by default and uses the _globally_ registered OpenTelemetry SDK instance (i.e. `GlobalOpenTelemetry`). So, if you don't use a custom, local OpenTelemetry SDK instance, there is no explicit setup required to use the Java API Client's OpenTelemetry instrumentation.
+
+===== Using a custom OpenTelemetry instance
+In case you are using https://opentelemetry.io/docs/instrumentation/java/manual/#example[manual OpenTelemetry instrumentation] with a custom OpenTelemetry SDK instance that is _not registered globally_, you can create the Java API Client using a custom OpenTelemetry instance. The following code snippet shows an example of using a custom OpenTelemetry instance.
+
+["source","java"]
+--------------------------------------------------
+include-tagged::{doc-tests-src}/getting_started/ConnectingTest.java[create-client-otel]
+--------------------------------------------------
+
 [[opentelemetry-config]]
 ==== Configuring the OpenTelemetry instrumentation
 
@@ -27,7 +39,7 @@ The following configuration options are available.
 
 [float]
 [[opentelemetry-config-enable]]
-===== Enable / Disable OpenTelemetry Instrumentation
+===== Enable / Disable the OpenTelemetry instrumentation
 
 [options="header"]
 |============
@@ -41,7 +53,7 @@ With this configuration option you can enable (default) or disable the built-in
 
 [float]
 [[opentelemetry-config-capture-search-query]]
-===== Capture Search Request Bodies
+===== Capture search request bodies
 
 [options="header"]
 |============

diff --git a/...client/src/test/java/co/elastic/clients/documentation/getting_started/ConnectingTest.java b/...client/src/test/java/co/elastic/clients/documentation/getting_started/ConnectingTest.java
@@ -26,7 +26,10 @@
 import co.elastic.clients.json.jackson.JacksonJsonpMapper;
 import co.elastic.clients.transport.ElasticsearchTransport;
 import co.elastic.clients.transport.TransportUtils;
+import co.elastic.clients.transport.instrumentation.OpenTelemetryForElasticsearch;
 import co.elastic.clients.transport.rest_client.RestClientTransport;
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.sdk.OpenTelemetrySdk;
 import org.apache.http.Header;
 import org.apache.http.HttpHost;
 import org.apache.http.auth.AuthScope;
@@ -82,6 +85,38 @@ public void createClient() throws Exception {
         //end::first-request
     }
 
+    @Disabled // we don't have a running ES
+    @Test
+    public void createClientWithOpenTelemetry() throws Exception {
+        //tag::create-client-otel
+        // URL and API key
+        String serverUrl = "https://localhost:9200";
+        String apiKey = "VnVhQ2ZHY0JDZGJrU...";
+
+        // Create the low-level client
+        RestClient restClient = RestClient
+                .builder(HttpHost.create(serverUrl))
+                .setDefaultHeaders(new Header[]{
+                        new BasicHeader("Authorization", "ApiKey " + apiKey)
+                })
+                .build();
+        // Create and configure custom OpenTelemetry instance
+        OpenTelemetry customOtel = OpenTelemetrySdk.builder().build();
+
+        // Create Instrumentation instance using the custom OpenTelemetry instance
+        // Second constructor argument allows to enable/disable search body capturing
+        OpenTelemetryForElasticsearch esOtelInstrumentation = new OpenTelemetryForElasticsearch(
+                customOtel, false);
+
+        // Create the transport with the custom Instrumentation instance
+        ElasticsearchTransport transport = new RestClientTransport(
+                restClient, new JacksonJsonpMapper(), null, esOtelInstrumentation);
+
+        // And create the API client
+        ElasticsearchClient esClient = new ElasticsearchClient(transport);
+        //end::create-client-otel
+    }
+
     @Disabled // we don't have a running ES
     @Test
     public void createSecureClientCert() throws Exception {