Micrometer Observation instrumentation (#4980)

Closes #4659

[Micrometer Observation](https://micrometer.io/docs/observation) is coming as part of the Micrometer 1.10 release and [Micrometer Tracing](https://micrometer.io/docs/tracing) is a new project. The idea of Micrometer Observation is that you instrument code once but you get multiple benefits out of it - e.g. you can get tracing, metrics, logging or whatever you see fit).

Since Armeria already supports Micrometer, we should add Micrometer Observation support so that except for metrics, spans could be created and tracing context propagation could happen too. 

Co-authored-by: Hannam Rhee <[email protected]>
Co-authored-by: jrhee17 <[email protected]>
Co-authored-by: Ikhun Um <[email protected]>
Co-authored-by: minux <[email protected]>

core/build.gradle

@@ -156,6 +156,13 @@ dependencies {
     optionalImplementation libs.brotli4j.osx
     optionalImplementation libs.brotli4j.osx.aarch64
     optionalImplementation libs.brotli4j.windows
+
+    // for testing the observation API with tracing
+    testImplementation (libs.micrometer.tracing.integration.test) {
+        exclude group: "org.mockito"
+    }
+    testImplementation libs.brave.context.slf4j
+    testImplementation libs.brave.instrumentation.http.tests
 }
 
 if (!rootProject.hasProperty('noWeb')) {

core/src/main/java/com/linecorp/armeria/client/observation/ClientObservationContext.java

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2023 LINE Corporation
+ *
+ * LINE Corporation licenses this file to you under the Apache License,
+ * version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at:
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+package com.linecorp.armeria.client.observation;
+
+import com.google.common.base.MoreObjects;
+
+import com.linecorp.armeria.client.ClientRequestContext;
+import com.linecorp.armeria.common.HttpRequest;
+import com.linecorp.armeria.common.RequestHeadersBuilder;
+import com.linecorp.armeria.common.annotation.UnstableApi;
+import com.linecorp.armeria.common.logging.RequestLog;
+
+import io.micrometer.observation.Observation.Context;
+import io.micrometer.observation.ObservationConvention;
+import io.micrometer.observation.ObservationHandler;
+import io.micrometer.observation.transport.RequestReplySenderContext;
+
+/**
+ * A {@link Context} which may be used in conjunction with {@link ObservationClient}
+ * to implement custom {@link ObservationConvention}s or {@link ObservationHandler}s.
+ * <pre>{@code
+ * ObservationConvention<ClientObservationContext> convention = ...
+ * WebClient.builder()
+ *          .decorator(ObservationClient.newDecorator(registry, convention))
+ * ...
+ * }</pre>
+ */
+@UnstableApi
+public final class ClientObservationContext
+        extends RequestReplySenderContext<RequestHeadersBuilder, RequestLog> {
+
+    private final ClientRequestContext clientRequestContext;
+    private final HttpRequest httpRequest;
+
+    ClientObservationContext(ClientRequestContext clientRequestContext, RequestHeadersBuilder carrier,
+                             HttpRequest httpRequest) {
+        super(RequestHeadersBuilder::add);
+        this.clientRequestContext = clientRequestContext;
+        this.httpRequest = httpRequest;
+        setCarrier(carrier);
+    }
+
+    /**
+     * The {@link ClientRequestContext} associated with this {@link Context}.
+     */
+    public ClientRequestContext requestContext() {
+        return clientRequestContext;
+    }
+
+    /**
+     * The {@link HttpRequest} associated with this {@link Context}.
+     */
+    public HttpRequest httpRequest() {
+        return httpRequest;
+    }
+
+    @Override
+    public String toString() {
+        return MoreObjects.toStringHelper(this).omitNullValues()
+                          .add("clientRequestContext", clientRequestContext)
+                          .add("httpRequest", httpRequest)
+                          .toString();
+    }
+}

core/src/main/java/com/linecorp/armeria/client/observation/DefaultHttpClientObservationConvention.java

@@ -0,0 +1,152 @@
+/*
+ * Copyright 2023 LINE Corporation
+ *
+ * LINE Corporation licenses this file to you under the Apache License,
+ * version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at:
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+package com.linecorp.armeria.client.observation;
+
+import static com.google.common.base.MoreObjects.firstNonNull;
+
+import java.net.InetSocketAddress;
+
+import com.google.common.collect.ImmutableList;
+
+import com.linecorp.armeria.client.ClientRequestContext;
+import com.linecorp.armeria.client.observation.HttpClientObservationDocumentation.HighCardinalityKeys;
+import com.linecorp.armeria.client.observation.HttpClientObservationDocumentation.LowCardinalityKeys;
+import com.linecorp.armeria.common.SerializationFormat;
+import com.linecorp.armeria.common.SessionProtocol;
+import com.linecorp.armeria.common.annotation.Nullable;
+import com.linecorp.armeria.common.logging.RequestLog;
+import com.linecorp.armeria.common.logging.RequestLogAccess;
+import com.linecorp.armeria.common.logging.RequestLogProperty;
+
+import io.micrometer.common.KeyValue;
+import io.micrometer.common.KeyValues;
+import io.micrometer.observation.Observation.Context;
+import io.micrometer.observation.ObservationConvention;
+
+class DefaultHttpClientObservationConvention implements ObservationConvention<ClientObservationContext> {
+
+    static final DefaultHttpClientObservationConvention INSTANCE =
+            new DefaultHttpClientObservationConvention();
+
+    @Override
+    public KeyValues getLowCardinalityKeyValues(ClientObservationContext context) {
+        final ClientRequestContext ctx = context.requestContext();
+        int expectedSize = 1;
+        final RequestLog log = context.getResponse();
+        KeyValue protocol = null;
+        KeyValue serializationFormat = null;
+        KeyValue statusCode = null;
+        if (log != null) {
+            protocol = LowCardinalityKeys.HTTP_PROTOCOL.withValue(protocol(log));
+            statusCode = LowCardinalityKeys.STATUS_CODE
+                    .withValue(log.responseStatus().codeAsText());
+            expectedSize = 3;
+            final String serFmt = serializationFormat(log);
+            if (serFmt != null) {
+                expectedSize = 4;
+                serializationFormat = LowCardinalityKeys.HTTP_SERIALIZATION_FORMAT.withValue(serFmt);
+            }
+        }
+        final ImmutableList.Builder<KeyValue> builder = ImmutableList.builderWithExpectedSize(expectedSize);
+        builder.add(LowCardinalityKeys.HTTP_METHOD.withValue(ctx.method().name()));
+        addIfNotNull(protocol, builder);
+        addIfNotNull(statusCode, builder);
+        addIfNotNull(serializationFormat, builder);
+        return KeyValues.of(builder.build());
+    }
+
+    private static void addIfNotNull(@Nullable KeyValue keyValue, ImmutableList.Builder<KeyValue> builder) {
+        if (keyValue != null) {
+            builder.add(keyValue);
+        }
+    }
+
+    @Override
+    public KeyValues getHighCardinalityKeyValues(ClientObservationContext context) {
+        final ClientRequestContext ctx = context.requestContext();
+        int expectedSize = 3;
+        KeyValue addressRemote = null;
+        KeyValue addressLocal = null;
+        KeyValue error = null;
+        if (context.getResponse() != null) {
+            final RequestLog log = ctx.log().ensureComplete();
+            final InetSocketAddress raddr = ctx.remoteAddress();
+            if (raddr != null) {
+                expectedSize = expectedSize + 1;
+                addressRemote = HighCardinalityKeys.ADDRESS_REMOTE.withValue(raddr.toString());
+            }
+            final InetSocketAddress laddr = ctx.localAddress();
+            if (laddr != null) {
+                expectedSize = expectedSize + 1;
+                addressLocal = HighCardinalityKeys.ADDRESS_LOCAL.withValue(laddr.toString());
+            }
+
+            final Throwable responseCause = log.responseCause();
+            if (responseCause != null) {
+                expectedSize = expectedSize + 1;
+                error = HighCardinalityKeys.ERROR.withValue(responseCause.toString());
+            } else if (log.responseStatus().isError()) {
+                expectedSize = expectedSize + 1;
+                error = HighCardinalityKeys.ERROR.withValue(log.responseStatus().codeAsText());
+            }
+        }
+        final ImmutableList.Builder<KeyValue> builder = ImmutableList.builderWithExpectedSize(expectedSize);
+        builder.add(HighCardinalityKeys.HTTP_PATH.withValue(ctx.path()),
+                    HighCardinalityKeys.HTTP_HOST.withValue(firstNonNull(ctx.authority(), "UNKNOWN")),
+                    HighCardinalityKeys.HTTP_URL.withValue(ctx.uri().toString()));
+        addIfNotNull(addressRemote, builder);
+        addIfNotNull(addressLocal, builder);
+        addIfNotNull(error, builder);
+        return KeyValues.of(builder.build());
+    }
+
+    /**
+     * Returns the {@link SessionProtocol#uriText()} of the {@link RequestLog}.
+     */
+    private static String protocol(RequestLog requestLog) {
+        return requestLog.sessionProtocol().uriText();
+    }
+
+    /**
+     * Returns the {@link SerializationFormat#uriText()} if it's not {@link SerializationFormat#NONE}.
+     */
+    @Nullable
+    private static String serializationFormat(RequestLog requestLog) {
+        final SerializationFormat serFmt = requestLog.serializationFormat();
+        return serFmt == SerializationFormat.NONE ? null : serFmt.uriText();
+    }
+
+    @Override
+    public String getName() {
+        return "http.client.requests";
+    }
+
+    @Override
+    public String getContextualName(ClientObservationContext context) {
+        final RequestLogAccess logAccess = context.requestContext().log();
+        if (logAccess.isAvailable(RequestLogProperty.NAME)) {
+            return logAccess.partial().fullName();
+        } else {
+            return context.getName();
+        }
+    }
+
+    @Override
+    public boolean supportsContext(Context context) {
+        return context instanceof ClientObservationContext;
+    }
+}