Reference doc update for OkHttp

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

@@ -1,3 +1,33 @@
+[[overview]]
+= OkHttpClient Instrumentation
+
+Micrometer supports https://square.github.io/okhttp/[OkHttp Client] instrumentation through Observation and metrics.
+
+[[okhttpclient-observation]]
+== OkHttpClient Observation
+
+Below you can find an example of how to instrument OkHttp Client  with https://docs.micrometer.io/micrometer/reference/observation.html[Micrometer Observation]. That means that depending on your Observation Handler configuration you instrument once, and can have multiple benefits out of it (e.g. metrics, distributed tracing).
+
+[source,java,subs=+attributes]
+-----
+// Setting up instrumentation
+include::{include-core-test-java}/io/micrometer/core/instrument/binder/okhttp3/OkHttpObservationInterceptorTest.java[tags=setup, indent=0]
+
+// Usage example
+include::{include-core-test-java}/io/micrometer/core/instrument/binder/okhttp3/OkHttpObservationInterceptorTest.java[tags=example, indent=0]
+-----
+
+The builder allows to change the default `ObservationConvention` as follows.
+
+[source,java,subs=+attributes]
+-----
+// Setting up instrumentation with custom convention
+include::{include-core-test-java}/io/micrometer/core/instrument/binder/okhttp3/OkHttpObservationInterceptorTest.java[tags=custom_convention, indent=0]
+-----
+
+[[okhttpclient-metrics]]
+== OkHttpClient Metrics
+
 Micrometer supports binding metrics to `OkHttpClient` through `EventListener`.
 
 You can collect metrics from `OkHttpClient` by adding `OkHttpMetricsEventListener` as follows:

micrometer-core/src/test/java/io/micrometer/core/instrument/binder/okhttp3/OkHttpObservationInterceptorTest.java

@@ -63,16 +63,18 @@ class OkHttpObservationInterceptorTest {
 
     private TestObservationRegistry observationRegistry = TestObservationRegistry.create();
 
+    private TestHandler testHandler = new TestHandler();
+
+    // tag::setup[]
     private OkHttpClient client = new OkHttpClient.Builder().addInterceptor(defaultInterceptorBuilder().build())
         .build();
 
-    private TestHandler testHandler = new TestHandler();
-
     private OkHttpObservationInterceptor.Builder defaultInterceptorBuilder() {
         return OkHttpObservationInterceptor.builder(observationRegistry, "okhttp.requests")
             .tags(KeyValues.of("foo", "bar"))
             .uriMapper(URI_MAPPER);
     }
+    // end::setup[]
 
     @BeforeEach
     void setup() {
@@ -85,6 +87,7 @@ void setup() {
     void timeSuccessfulWithDefaultObservation(@WiremockResolver.Wiremock WireMockServer server) throws IOException {
         client = new OkHttpClient.Builder().addInterceptor(defaultInterceptorBuilder().build()).build();
         server.stubFor(any(anyUrl()));
+        // tag::example[]
         Request request = new Request.Builder().url(server.baseUrl()).build();
 
         makeACall(client, request);
@@ -97,17 +100,20 @@ void timeSuccessfulWithDefaultObservation(@WiremockResolver.Wiremock WireMockSer
         assertThat(testHandler.context).isNotNull();
         assertThat(testHandler.context.getAllKeyValues()).contains(KeyValue.of("foo", "bar"),
                 KeyValue.of("status", "200"));
+        // end::example[]
         server.verify(WireMock.getRequestedFor(WireMock.urlEqualTo("/")).withHeader("foo", WireMock.equalTo("bar")));
     }
 
     @Test
     void timeSuccessfulWithObservationConvention(@WiremockResolver.Wiremock WireMockServer server) throws IOException {
+        // tag::custom_convention[]
         MyConvention myConvention = new MyConvention();
         client = new OkHttpClient.Builder()
             .addInterceptor(defaultInterceptorBuilder()
                 .observationConvention(new StandardizedOkHttpObservationConvention(myConvention))
                 .build())
             .build();
+        // end::custom_convention[]
         server.stubFor(any(anyUrl()));
         Request request = new Request.Builder().url(server.baseUrl()).build();