Document Java HttpClient instrumentation

 The instrumentation has existed for longer, but it was recently moved to the micrometer-java11 module. This adds documentation for it with the new module.

 Resolves gh-4752

docs/antora.yml

@@ -19,3 +19,4 @@ asciidoc:
     include-resources: 'example$docs-src/test/resources'
     include-core-test-java: 'example$core-test'
     include-micrometer-test-java: 'example$micrometer-test'
+    include-micrometer-java11-test: 'example$micrometer-java11-test'

docs/modules/ROOT/examples/micrometer-java11-test

@@ -0,0 +1 @@
+../../../../micrometer-java11/src/test/java

docs/modules/ROOT/nav.adoc

@@ -41,6 +41,7 @@
 ** xref:reference/db.adoc[Database]
 ** xref:reference/grpc.adoc[gRPC]
 ** xref:reference/httpcomponents.adoc[HttpComponents Client]
+** xreg:reference/java-httpclient.adoc[Java HttpClient]
 ** xref:reference/jetty.adoc[Jetty and Jersey]
 ** xref:reference/jvm.adoc[JVM]
 ** xref:reference/kafka.adoc[Kafka]

docs/modules/ROOT/pages/reference/java-httpclient.adoc

@@ -0,0 +1,41 @@
+= Java HttpClient instrumentation
+
+Since Java 11, an `HttpClient` is provided as part of the JDK. See https://openjdk.org/groups/net/httpclient/intro.html[this introduction] to it. Micrometer provides instrumentation of this via a `micrometer-java11` module. This module requires Java 11 or later.
+
+For Gradle, add the following implementation:
+
+[source,groovy,subs=+attributes]
+----
+implementation 'io.micrometer:micrometer-java11'
+----
+
+For Maven, add the following dependency:
+
+[source,xml,subs=+attributes]
+----
+<dependency>
+  <groupId>io.micrometer</groupId>
+  <artifactId>micrometer-java11</artifactId>
+</dependency>
+----
+
+Create an `HttpClient` as you normally would. For example:
+
+[source,java,subs=+attributes]
+----
+include::{include-micrometer-java11-test}/io/micrometer/java11/instrument/binder/jdk/MicrometerHttpClientTests.java[tags=setupClient,indent=0]
+----
+
+You can instrument this `HttpClient` as follows with an `ObservationRegistry`:
+
+[source,java,subs=+attributes]
+----
+include::{include-micrometer-java11-test}/io/micrometer/java11/instrument/binder/jdk/MicrometerHttpClientTests.java[tags=observationInstrumentation,indent=0]
+----
+
+Alternatively, if you are not using an `ObservationRegistry`, you can instrument with only a `MeterRegistry` as follows:
+
+[source,java,subs=+attributes]
+----
+include::{include-micrometer-java11-test}/io/micrometer/java11/instrument/binder/jdk/MicrometerHttpClientTests.java[tags=meterRegistryInstrumentation,indent=0]
+----

micrometer-java11/src/test/java/io/micrometer/java11/instrument/binder/jdk/MicrometerHttpClientTests.java

@@ -42,8 +42,11 @@ class MicrometerHttpClientTests {
 
     MeterRegistry meterRegistry = new SimpleMeterRegistry();
 
+    // tag::setupClient[]
     HttpClient httpClient = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(2)).build();
 
+    // end::setupClient[]
+
     @BeforeEach
     void setup() {
         stubFor(any(urlEqualTo("/metrics")).willReturn(ok().withBody("body")));
@@ -62,9 +65,11 @@ void shouldInstrumentHttpClientWithObservation(WireMockRuntimeInfo wmInfo)
             .uri(URI.create(wmInfo.getHttpBaseUrl() + "/metrics"))
             .build();
 
+        // tag::observationInstrumentation[]
         HttpClient observedClient = MicrometerHttpClient.instrumentationBuilder(httpClient, meterRegistry)
             .observationRegistry(observationRegistry)
             .build();
+        // end::observationInstrumentation[]
         observedClient.send(request, HttpResponse.BodyHandlers.ofString());
 
         verify(anyRequestedFor(urlEqualTo("/metrics")).withHeader("foo", equalTo("bar")));
@@ -78,7 +83,9 @@ void shouldInstrumentHttpClientWithTimer(WireMockRuntimeInfo wmInfo) throws IOEx
             .uri(URI.create(wmInfo.getHttpBaseUrl() + "/metrics"))
             .build();
 
+        // tag::meterRegistryInstrumentation[]
         HttpClient observedClient = MicrometerHttpClient.instrumentationBuilder(httpClient, meterRegistry).build();
+        // end::meterRegistryInstrumentation[]
         observedClient.send(request, HttpResponse.BodyHandlers.ofString());
 
         thenMeterRegistryContainsHttpClientTags();