Better qualify Java HttpClient instrumentation package name (#13296)

trask · laurit · web-flow · commit 74a9fd0353ba · 2025-02-18T17:46:36.000Z
Co-authored-by: Lauri Tulmin &lt;ltulmin@splunk.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+### Migration notes
+
+- The `java.net.http.HttpClient` instrumentation package
+  `io.opentelemetry.instrumentation.httpclient` was deprecated in favor of the new package name
+  `io.opentelemetry.instrumentation.javahttpclient`
+
 ## Version 2.13.0 (2025-02-17)
 
 ### Migration notes
diff --git a/instrumentation/java-http-client/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/javahttpclient/HttpClientInstrumentation.java b/instrumentation/java-http-client/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/javahttpclient/HttpClientInstrumentation.java
@@ -3,12 +3,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.javaagent.instrumentation.httpclient;
+package io.opentelemetry.javaagent.instrumentation.javahttpclient;
 
 import static io.opentelemetry.javaagent.bootstrap.Java8BytecodeBridge.currentContext;
 import static io.opentelemetry.javaagent.extension.matcher.AgentElementMatchers.extendsClass;
 import static io.opentelemetry.javaagent.extension.matcher.AgentElementMatchers.hasClassesNamed;
-import static io.opentelemetry.javaagent.instrumentation.httpclient.JavaHttpClientSingletons.instrumenter;
+import static io.opentelemetry.javaagent.instrumentation.javahttpclient.JavaHttpClientSingletons.instrumenter;
 import static net.bytebuddy.matcher.ElementMatchers.isMethod;
 import static net.bytebuddy.matcher.ElementMatchers.isPublic;
 import static net.bytebuddy.matcher.ElementMatchers.nameStartsWith;
@@ -19,8 +19,8 @@
 
 import io.opentelemetry.context.Context;
 import io.opentelemetry.context.Scope;
-import io.opentelemetry.instrumentation.httpclient.internal.CompletableFutureWrapper;
-import io.opentelemetry.instrumentation.httpclient.internal.ResponseConsumer;
+import io.opentelemetry.instrumentation.javahttpclient.internal.CompletableFutureWrapper;
+import io.opentelemetry.instrumentation.javahttpclient.internal.ResponseConsumer;
 import io.opentelemetry.javaagent.bootstrap.CallDepth;
 import io.opentelemetry.javaagent.extension.instrumentation.TypeInstrumentation;
 import io.opentelemetry.javaagent.extension.instrumentation.TypeTransformer;
diff --git a/instrumentation/java-http-client/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/javahttpclient/HttpClientInstrumentationModule.java b/instrumentation/java-http-client/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/javahttpclient/HttpClientInstrumentationModule.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.javaagent.instrumentation.httpclient;
+package io.opentelemetry.javaagent.instrumentation.javahttpclient;
 
 import static java.util.Arrays.asList;
 
diff --git a/instrumentation/java-http-client/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/javahttpclient/HttpHeadersInstrumentation.java b/instrumentation/java-http-client/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/javahttpclient/HttpHeadersInstrumentation.java
@@ -3,10 +3,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.javaagent.instrumentation.httpclient;
+package io.opentelemetry.javaagent.instrumentation.javahttpclient;
 
 import static io.opentelemetry.javaagent.extension.matcher.AgentElementMatchers.extendsClass;
-import static io.opentelemetry.javaagent.instrumentation.httpclient.JavaHttpClientSingletons.setter;
+import static io.opentelemetry.javaagent.instrumentation.javahttpclient.JavaHttpClientSingletons.setter;
 import static net.bytebuddy.matcher.ElementMatchers.isMethod;
 import static net.bytebuddy.matcher.ElementMatchers.nameStartsWith;
 import static net.bytebuddy.matcher.ElementMatchers.named;
diff --git a/instrumentation/java-http-client/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/javahttpclient/JavaHttpClientSingletons.java b/instrumentation/java-http-client/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/javahttpclient/JavaHttpClientSingletons.java
@@ -3,12 +3,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.javaagent.instrumentation.httpclient;
+package io.opentelemetry.javaagent.instrumentation.javahttpclient;
 
 import io.opentelemetry.api.GlobalOpenTelemetry;
 import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
-import io.opentelemetry.instrumentation.httpclient.internal.HttpHeadersSetter;
-import io.opentelemetry.instrumentation.httpclient.internal.JavaHttpClientInstrumenterBuilderFactory;
+import io.opentelemetry.instrumentation.javahttpclient.internal.HttpHeadersSetter;
+import io.opentelemetry.instrumentation.javahttpclient.internal.JavaHttpClientInstrumenterBuilderFactory;
 import io.opentelemetry.javaagent.bootstrap.internal.JavaagentHttpClientInstrumenters;
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
diff --git a/instrumentation/java-http-client/javaagent/src/test/java/io/opentelemetry/javaagent/instrumentation/javahttpclient/JavaHttpClientTest.java b/instrumentation/java-http-client/javaagent/src/test/java/io/opentelemetry/javaagent/instrumentation/javahttpclient/JavaHttpClientTest.java
@@ -3,9 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.javaagent.instrumentation.httpclient;
+package io.opentelemetry.javaagent.instrumentation.javahttpclient;
 
-import io.opentelemetry.instrumentation.httpclient.AbstractJavaHttpClientTest;
+import io.opentelemetry.instrumentation.javahttpclient.AbstractJavaHttpClientTest;
 import io.opentelemetry.instrumentation.testing.junit.InstrumentationExtension;
 import io.opentelemetry.instrumentation.testing.junit.http.HttpClientInstrumentationExtension;
 import io.opentelemetry.instrumentation.testing.junit.http.HttpClientTestOptions;
diff --git a/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/httpclient/JavaHttpClientTelemetry.java b/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/httpclient/JavaHttpClientTelemetry.java
@@ -7,13 +7,19 @@
 
 import io.opentelemetry.api.OpenTelemetry;
 import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
-import io.opentelemetry.instrumentation.httpclient.internal.HttpHeadersSetter;
-import io.opentelemetry.instrumentation.httpclient.internal.OpenTelemetryHttpClient;
+import io.opentelemetry.instrumentation.javahttpclient.internal.HttpHeadersSetter;
+import io.opentelemetry.instrumentation.javahttpclient.internal.OpenTelemetryHttpClient;
 import java.net.http.HttpClient;
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
 
-/** Entrypoint for instrumenting Java HTTP Client. */
+/**
+ * Entrypoint for instrumenting Java HTTP Client.
+ *
+ * @deprecated Use {@link io.opentelemetry.instrumentation.javahttpclient.JavaHttpClientTelemetry}
+ *     instead.
+ */
+@Deprecated
 public final class JavaHttpClientTelemetry {
 
   /**
diff --git a/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/httpclient/JavaHttpClientTelemetryBuilder.java b/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/httpclient/JavaHttpClientTelemetryBuilder.java
@@ -12,13 +12,18 @@
 import io.opentelemetry.instrumentation.api.instrumenter.SpanNameExtractor;
 import io.opentelemetry.instrumentation.api.semconv.http.HttpClientAttributesExtractorBuilder;
 import io.opentelemetry.instrumentation.httpclient.internal.Experimental;
-import io.opentelemetry.instrumentation.httpclient.internal.HttpHeadersSetter;
-import io.opentelemetry.instrumentation.httpclient.internal.JavaHttpClientInstrumenterBuilderFactory;
+import io.opentelemetry.instrumentation.javahttpclient.internal.HttpHeadersSetter;
+import io.opentelemetry.instrumentation.javahttpclient.internal.JavaHttpClientInstrumenterBuilderFactory;
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
 import java.util.Collection;
 import java.util.function.Function;
 
+/**
+ * @deprecated Use {@link
+ *     io.opentelemetry.instrumentation.javahttpclient.JavaHttpClientTelemetryBuilder} instead.
+ */
+@Deprecated
 public final class JavaHttpClientTelemetryBuilder {
 
   private final DefaultHttpClientInstrumenterBuilder<HttpRequest, HttpResponse<?>> builder;
diff --git a/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/httpclient/internal/Experimental.java b/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/httpclient/internal/Experimental.java
@@ -13,7 +13,11 @@
  * This class is internal and experimental. Its APIs are unstable and can change at any time. Its
  * APIs (or a version of them) may be promoted to the public stable API in the future, but no
  * guarantees are made.
+ *
+ * @deprecated Use {@link io.opentelemetry.instrumentation.javahttpclient.internal.Experimental}
+ *     instead.
  */
+@Deprecated
 public final class Experimental {
 
   @Nullable
diff --git a/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/JavaHttpClientTelemetry.java b/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/JavaHttpClientTelemetry.java
@@ -0,0 +1,49 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.javahttpclient;
+
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
+import io.opentelemetry.instrumentation.javahttpclient.internal.HttpHeadersSetter;
+import io.opentelemetry.instrumentation.javahttpclient.internal.OpenTelemetryHttpClient;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+
+/** Entrypoint for instrumenting Java HTTP Client. */
+public final class JavaHttpClientTelemetry {
+
+  /**
+   * Returns a new {@link JavaHttpClientTelemetry} configured with the given {@link OpenTelemetry}.
+   */
+  public static JavaHttpClientTelemetry create(OpenTelemetry openTelemetry) {
+    return builder(openTelemetry).build();
+  }
+
+  public static JavaHttpClientTelemetryBuilder builder(OpenTelemetry openTelemetry) {
+    return new JavaHttpClientTelemetryBuilder(openTelemetry);
+  }
+
+  private final Instrumenter<HttpRequest, HttpResponse<?>> instrumenter;
+  private final HttpHeadersSetter headersSetter;
+
+  JavaHttpClientTelemetry(
+      Instrumenter<HttpRequest, HttpResponse<?>> instrumenter, HttpHeadersSetter headersSetter) {
+    this.instrumenter = instrumenter;
+    this.headersSetter = headersSetter;
+  }
+
+  /**
+   * Construct a new OpenTelemetry tracing-enabled {@link HttpClient} using the provided {@link
+   * HttpClient} instance.
+   *
+   * @param client An instance of HttpClient configured as desired.
+   * @return a tracing-enabled {@link HttpClient}.
+   */
+  public HttpClient newHttpClient(HttpClient client) {
+    return new OpenTelemetryHttpClient(client, instrumenter, headersSetter);
+  }
+}
diff --git a/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/JavaHttpClientTelemetryBuilder.java b/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/JavaHttpClientTelemetryBuilder.java
@@ -0,0 +1,106 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.javahttpclient;
+
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.instrumentation.api.incubator.builder.internal.DefaultHttpClientInstrumenterBuilder;
+import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor;
+import io.opentelemetry.instrumentation.api.instrumenter.SpanNameExtractor;
+import io.opentelemetry.instrumentation.api.semconv.http.HttpClientAttributesExtractorBuilder;
+import io.opentelemetry.instrumentation.javahttpclient.internal.Experimental;
+import io.opentelemetry.instrumentation.javahttpclient.internal.HttpHeadersSetter;
+import io.opentelemetry.instrumentation.javahttpclient.internal.JavaHttpClientInstrumenterBuilderFactory;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.util.Collection;
+import java.util.function.Function;
+
+public final class JavaHttpClientTelemetryBuilder {
+
+  private final DefaultHttpClientInstrumenterBuilder<HttpRequest, HttpResponse<?>> builder;
+  private final OpenTelemetry openTelemetry;
+
+  static {
+    Experimental.internalSetEmitExperimentalTelemetry(
+        (builder, emit) -> builder.builder.setEmitExperimentalHttpClientMetrics(emit));
+  }
+
+  JavaHttpClientTelemetryBuilder(OpenTelemetry openTelemetry) {
+    builder = JavaHttpClientInstrumenterBuilderFactory.create(openTelemetry);
+    this.openTelemetry = openTelemetry;
+  }
+
+  /**
+   * Adds an additional {@link AttributesExtractor} to invoke to set attributes to instrumented
+   * items. The {@link AttributesExtractor} will be executed after all default extractors.
+   */
+  @CanIgnoreReturnValue
+  public JavaHttpClientTelemetryBuilder addAttributesExtractor(
+      AttributesExtractor<? super HttpRequest, ? super HttpResponse<?>> attributesExtractor) {
+    builder.addAttributesExtractor(attributesExtractor);
+    return this;
+  }
+
+  /**
+   * Configures the HTTP request headers that will be captured as span attributes.
+   *
+   * @param requestHeaders A list of HTTP header names.
+   */
+  @CanIgnoreReturnValue
+  public JavaHttpClientTelemetryBuilder setCapturedRequestHeaders(
+      Collection<String> requestHeaders) {
+    builder.setCapturedRequestHeaders(requestHeaders);
+    return this;
+  }
+
+  /**
+   * Configures the HTTP response headers that will be captured as span attributes.
+   *
+   * @param responseHeaders A list of HTTP header names.
+   */
+  @CanIgnoreReturnValue
+  public JavaHttpClientTelemetryBuilder setCapturedResponseHeaders(
+      Collection<String> responseHeaders) {
+    builder.setCapturedResponseHeaders(responseHeaders);
+    return this;
+  }
+
+  /**
+   * Configures the instrumentation to recognize an alternative set of HTTP request methods.
+   *
+   * <p>By default, this instrumentation defines "known" methods as the ones listed in <a
+   * href="https://www.rfc-editor.org/rfc/rfc9110.html#name-methods">RFC9110</a> and the PATCH
+   * method defined in <a href="https://www.rfc-editor.org/rfc/rfc5789.html">RFC5789</a>.
+   *
+   * <p>Note: calling this method <b>overrides</b> the default known method sets completely; it does
+   * not supplement it.
+   *
+   * @param knownMethods A set of recognized HTTP request methods.
+   * @see HttpClientAttributesExtractorBuilder#setKnownMethods(Collection)
+   */
+  @CanIgnoreReturnValue
+  public JavaHttpClientTelemetryBuilder setKnownMethods(Collection<String> knownMethods) {
+    builder.setKnownMethods(knownMethods);
+    return this;
+  }
+
+  /** Sets custom {@link SpanNameExtractor} via transform function. */
+  @CanIgnoreReturnValue
+  public JavaHttpClientTelemetryBuilder setSpanNameExtractor(
+      Function<
+              SpanNameExtractor<? super HttpRequest>,
+              ? extends SpanNameExtractor<? super HttpRequest>>
+          spanNameExtractorTransformer) {
+    builder.setSpanNameExtractor(spanNameExtractorTransformer);
+    return this;
+  }
+
+  public JavaHttpClientTelemetry build() {
+    return new JavaHttpClientTelemetry(
+        builder.build(), new HttpHeadersSetter(openTelemetry.getPropagators()));
+  }
+}
diff --git a/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/internal/CompletableFutureWrapper.java b/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/internal/CompletableFutureWrapper.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.httpclient.internal;
+package io.opentelemetry.instrumentation.javahttpclient.internal;
 
 import io.opentelemetry.context.Context;
 import io.opentelemetry.context.Scope;
diff --git a/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/internal/Experimental.java b/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/internal/Experimental.java
@@ -0,0 +1,36 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.javahttpclient.internal;
+
+import io.opentelemetry.instrumentation.javahttpclient.JavaHttpClientTelemetryBuilder;
+import java.util.function.BiConsumer;
+import javax.annotation.Nullable;
+
+/**
+ * This class is internal and experimental. Its APIs are unstable and can change at any time. Its
+ * APIs (or a version of them) may be promoted to the public stable API in the future, but no
+ * guarantees are made.
+ */
+public final class Experimental {
+
+  @Nullable
+  private static volatile BiConsumer<JavaHttpClientTelemetryBuilder, Boolean>
+      setEmitExperimentalTelemetry;
+
+  public static void setEmitExperimentalTelemetry(
+      JavaHttpClientTelemetryBuilder builder, boolean emitExperimentalTelemetry) {
+    if (setEmitExperimentalTelemetry != null) {
+      setEmitExperimentalTelemetry.accept(builder, emitExperimentalTelemetry);
+    }
+  }
+
+  public static void internalSetEmitExperimentalTelemetry(
+      BiConsumer<JavaHttpClientTelemetryBuilder, Boolean> setEmitExperimentalTelemetry) {
+    Experimental.setEmitExperimentalTelemetry = setEmitExperimentalTelemetry;
+  }
+
+  private Experimental() {}
+}
diff --git a/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/internal/HttpHeadersSetter.java b/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/internal/HttpHeadersSetter.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.httpclient.internal;
+package io.opentelemetry.instrumentation.javahttpclient.internal;
 
 import io.opentelemetry.context.Context;
 import io.opentelemetry.context.propagation.ContextPropagators;
diff --git a/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/internal/HttpRequestWrapper.java b/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/internal/HttpRequestWrapper.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.httpclient.internal;
+package io.opentelemetry.instrumentation.javahttpclient.internal;
 
 import java.net.URI;
 import java.net.http.HttpClient;
diff --git a/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/internal/JavaHttpClientAttributesGetter.java b/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/internal/JavaHttpClientAttributesGetter.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.httpclient.internal;
+package io.opentelemetry.instrumentation.javahttpclient.internal;
 
 import io.opentelemetry.instrumentation.api.semconv.http.HttpClientAttributesGetter;
 import java.net.http.HttpClient;
diff --git a/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/internal/JavaHttpClientInstrumenterBuilderFactory.java b/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/internal/JavaHttpClientInstrumenterBuilderFactory.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.httpclient.internal;
+package io.opentelemetry.instrumentation.javahttpclient.internal;
 
 import io.opentelemetry.api.OpenTelemetry;
 import io.opentelemetry.instrumentation.api.incubator.builder.internal.DefaultHttpClientInstrumenterBuilder;
diff --git a/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/internal/OpenTelemetryHttpClient.java b/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/internal/OpenTelemetryHttpClient.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.instrumentation.httpclient.internal;
+package io.opentelemetry.instrumentation.javahttpclient.internal;
 
 import io.opentelemetry.context.Context;
 import io.opentelemetry.context.Scope;
diff --git a/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/internal/ResponseConsumer.java b/instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient/internal/ResponseConsumer.java
diff --git a/instrumentation/java-http-client/library/src/test/java/io/opentelemetry/instrumentation/httpclient/JavaHttpClientTest.java b/instrumentation/java-http-client/library/src/test/java/io/opentelemetry/instrumentation/httpclient/JavaHttpClientTest.java
diff --git a/instrumentation/java-http-client/library/src/test/java/io/opentelemetry/instrumentation/javahttpclient/JavaHttpClientTest.java b/instrumentation/java-http-client/library/src/test/java/io/opentelemetry/instrumentation/javahttpclient/JavaHttpClientTest.java
diff --git a/instrumentation/java-http-client/testing/src/main/java/io/opentelemetry/instrumentation/javahttpclient/AbstractJavaHttpClientTest.java b/instrumentation/java-http-client/testing/src/main/java/io/opentelemetry/instrumentation/javahttpclient/AbstractJavaHttpClientTest.java
