HttpClient reference documentation

docs/modules/ROOT/nav.adoc

@@ -36,6 +36,7 @@
 ** xref:implementations/wavefront.adoc[Wavefront]
 * xref:reference.adoc[Reference Instrumentations]
 ** xref:reference/commons-pool.adoc[Apache Commons Pool]
+** xref:reference/httpcomponents.adoc[Apache HttpComponents Client]
 ** xref:reference/jvm.adoc[JVM]
 ** xref:reference/cache.adoc[Cache]
 ** xref:reference/okhttpclient.adoc[OkHttpClient]

docs/modules/ROOT/pages/reference/httpcomponents.adoc

@@ -0,0 +1,30 @@
+[[overview]]
+= Apache HttpComponents Client Instrumentation
+
+IMPORTANT: This section requires usage of Apache HttpComponents Client at least in version 5.
+
+https://hc.apache.org/index.html/[Apache HttpComponents Client] is an HTTP/1.1 compliant HTTP agent implementation.
+
+Below you can find an example of how to instrument Apache HttpComponents Client with Micrometer.
+
+Example of classic, blocking HTTP client.
+
+[source,java,subs=+attributes]
+-----
+// Setting up instrumentation (you need to create a client from the builder)
+include::{include-core-test-java}/io/micrometer/core/instrument/binder/httpcomponents/hc5/ObservationExecChainHandlerIntegrationTest.java[tags=setup_classic, indent=0]
+
+// Usage example
+include::{include-core-test-java}/io/micrometer/core/instrument/binder/httpcomponents/hc5/ObservationExecChainHandlerIntegrationTest.java[tags=example_classic, indent=0]
+-----
+
+Example of async HTTP client.
+
+[source,java,subs=+attributes]
+-----
+// Setting up instrumentation (you need to create a client from the builder)
+include::{include-core-test-java}/io/micrometer/core/instrument/binder/httpcomponents/hc5/ObservationExecChainHandlerIntegrationTest.java[tags=setup_async, indent=0]
+
+// Usage example
+include::{include-core-test-java}/io/micrometer/core/instrument/binder/httpcomponents/hc5/ObservationExecChainHandlerIntegrationTest.java[tags=example_async, indent=0]
+-----

micrometer-core/src/test/java/io/micrometer/core/instrument/binder/httpcomponents/hc5/ObservationExecChainHandlerIntegrationTest.java

@@ -80,6 +80,7 @@ class ClassicClient {
         @Test
         void recordSuccessfulExchanges(@WiremockResolver.Wiremock WireMockServer server) throws Exception {
             server.stubFor(any(anyUrl()));
+            // tag::example_classic[]
             try (CloseableHttpClient client = classicClient()) {
                 executeClassic(client, new HttpGet(server.baseUrl()));
             }
@@ -88,6 +89,7 @@ void recordSuccessfulExchanges(@WiremockResolver.Wiremock WireMockServer server)
                 .hasLowCardinalityKeyValue("outcome", "SUCCESS")
                 .hasLowCardinalityKeyValue("status", "200")
                 .hasLowCardinalityKeyValue("method", "GET");
+            // end::example_classic[]
         }
 
         @Test
@@ -227,6 +229,7 @@ class AsyncClient {
         @Test
         void recordSuccessfulExchanges(@WiremockResolver.Wiremock WireMockServer server) throws Exception {
             server.stubFor(any(anyUrl()));
+            // tag::example_async[]
             try (CloseableHttpAsyncClient client = asyncClient()) {
                 SimpleHttpRequest request = SimpleRequestBuilder.get(server.baseUrl()).build();
                 executeAsync(client, request);
@@ -236,6 +239,7 @@ void recordSuccessfulExchanges(@WiremockResolver.Wiremock WireMockServer server)
                 .hasLowCardinalityKeyValue("outcome", "SUCCESS")
                 .hasLowCardinalityKeyValue("status", "200")
                 .hasLowCardinalityKeyValue("method", "GET");
+            // end::example_async[]
         }
 
         @Test
@@ -384,12 +388,14 @@ private CloseableHttpClient classicClient() {
             .setConnectTimeout(2000L, TimeUnit.MILLISECONDS)
             .build();
 
+        // tag::setup_classic[]
         HttpClientBuilder clientBuilder = HttpClients.custom()
             .setRetryStrategy(retryStrategy)
             .addExecInterceptorLast("micrometer", new ObservationExecChainHandler(observationRegistry))
             .setConnectionManager(PoolingHttpClientConnectionManagerBuilder.create()
                 .setDefaultConnectionConfig(connectionConfig)
                 .build());
+        // end::setup_classic[]
 
         return clientBuilder.build();
     }
@@ -413,12 +419,14 @@ private CloseableHttpAsyncClient asyncClient() {
             .setConnectTimeout(1000, TimeUnit.MILLISECONDS)
             .build();
 
+        // tag::setup_async[]
         HttpAsyncClientBuilder clientBuilder = HttpAsyncClients.custom()
             .addExecInterceptorLast("micrometer", new ObservationExecChainHandler(observationRegistry))
             .setRetryStrategy(retryStrategy)
             .setConnectionManager(PoolingAsyncClientConnectionManagerBuilder.create()
                 .setDefaultConnectionConfig(connectionConfig)
                 .build());
+        // end::setup_async[]
 
         return clientBuilder.build();
     }