OkHttp3 instrumentation with observation api (#3176)

* WIP

* WIP on KeyValuesConvention

* Generates OTel semconventions instead of depend on the JARs

* Added an ObservationFilter

* Adds mechanism to change observation names depending (#3235)

* WIP

* Introduces naming conventions

* Polish

* Removing OTel from the repo

since OTel is unstable we've decided it to move it out to an experimental repository that will implement all the interfaces that micrometer provides

* Added missing headers

* Removing the MeterIdSemanticNameProvider and the MeterFilter method for it

* Fixed the invalid line entry

* Polishing

- removed the service locator like solution in ObservationRegistry for naming conventions. Users will have to provide a convention manually (or in frameworks like Boot it will happen for them)
- added noop impls for conventions since we have no-null apis

* Fixed formatting

Author: marcingrzejszczak

build.gradle

@@ -296,7 +296,7 @@ subprojects {
                 }
             }
 
-            if (!(project.name in ['micrometer-commons', 'micrometer-observation', 'micrometer-observation-test'])) {
+            if (!(project.name in ['micrometer-commons', 'micrometer-observation', 'micrometer-observation-conventions', 'micrometer-observation-test'])) {
                 apply plugin: 'me.champeau.gradle.japicmp'
                 apply plugin: 'de.undercouch.download'
 

micrometer-commons/src/main/java/io/micrometer/common/KeyValue.java

@@ -15,6 +15,8 @@
  */
 package io.micrometer.common;
 
+import java.util.function.Predicate;
+
 /**
  * Key/value pair representing a dimension of a meter used to classify and drill into
  * measurements.
@@ -32,6 +34,10 @@ static KeyValue of(String key, String value) {
         return new ImmutableKeyValue(key, value);
     }
 
+    static KeyValue of(String key, Object value, Predicate<Object> validator) {
+        return new ValidatedKeyValue<>(key, value, validator);
+    }
+
     @Override
     default int compareTo(KeyValue o) {
         return getKey().compareTo(o.getKey());

micrometer-commons/src/main/java/io/micrometer/common/ValidatedKeyValue.java

@@ -0,0 +1,61 @@
+/**
+ * Copyright 2022 VMware, Inc.
+ * <p>
+ * Licensed 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
+ * <p>
+ * https://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * 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 io.micrometer.common;
+
+import java.util.function.Predicate;
+
+/**
+ * {@link KeyValue} with value validation.
+ *
+ * @param <T>
+ * @author Marcin Grzejszczak
+ * @since 1.10.0
+ */
+class ValidatedKeyValue<T> implements KeyValue {
+
+    private final String key;
+
+    private final T value;
+
+    ValidatedKeyValue(String key, T value, Predicate<Object> validator) {
+        this.key = key;
+        this.value = assertValue(validator, value);
+    }
+
+    @Override
+    public String getKey() {
+        return this.key;
+    }
+
+    @Override
+    public String getValue() {
+        return String.valueOf(this.value);
+    }
+
+    private T assertValue(Predicate<Object> validator, T value) {
+        if (!validator.test(value)) {
+            throw new IllegalArgumentException(
+                    "Argument [" + this.value + "] does not follow required format for key [" + this.key + "]");
+        }
+        return value;
+    }
+
+    @Override
+    public String toString() {
+        return "tag(" + key + "=" + value + ")";
+    }
+
+}

micrometer-commons/src/main/java/io/micrometer/common/docs/KeyName.java

@@ -18,6 +18,7 @@
 import io.micrometer.common.KeyValue;
 
 import java.util.Arrays;
+import java.util.function.Predicate;
 
 /**
  * Represents a key name used for documenting instrumentation.
@@ -51,4 +52,14 @@ default KeyValue of(String value) {
         return KeyValue.of(getKeyName(), value);
     }
 
+    /**
+     * Creates a key value for the given key name.
+     * @param value value for key
+     * @param validator value validator
+     * @return key value
+     */
+    default KeyValue of(String value, Predicate<Object> validator) {
+        return KeyValue.of(getKeyName(), value, validator);
+    }
+
 }

micrometer-commons/src/main/java/io/micrometer/common/docs/SemanticNameProvider.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2022 VMware, Inc.
+ *
+ * Licensed 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 io.micrometer.common.docs;
+
+/**
+ * Renames the metric / trace / observation depending on standards.
+ *
+ * @author Marcin Grzejszczak
+ * @since 1.10.0
+ */
+public interface SemanticNameProvider<T> {
+
+    /**
+     * Will return a standardized name.
+     * @return name
+     */
+    String getName();
+
+    /**
+     * Returns {@code true} when this {@link SemanticNameProvider} should be applied and a
+     * new name should be set.
+     * @param object object against which we determine whether this provider is applicable
+     * or not
+     * @return {@code true} when new name should be applied
+     */
+    boolean isApplicable(T object);
+
+}

micrometer-core/build.gradle

@@ -2,6 +2,7 @@ description 'Core module of Micrometer containing instrumentation API and implem
 
 dependencies {
     api project(":micrometer-commons")
+    api project(":micrometer-observation")
 
     // TODO(anuraaga): HdrHistogram is exposed in the micrometer API but probably shouldn't be
     api 'org.hdrhistogram:HdrHistogram'

micrometer-core/src/main/java/io/micrometer/core/instrument/binder/okhttp3/DefaultOkHttpKeyValuesProvider.java

@@ -0,0 +1,145 @@
+/*
+ * Copyright 2017 VMware, Inc.
+ *
+ * Licensed 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 io.micrometer.core.instrument.binder.okhttp3;
+
+import io.micrometer.common.KeyValue;
+import io.micrometer.common.KeyValues;
+import io.micrometer.common.lang.NonNullApi;
+import io.micrometer.common.lang.NonNullFields;
+import io.micrometer.common.lang.Nullable;
+import io.micrometer.core.instrument.Tag;
+import io.micrometer.core.instrument.Tags;
+import okhttp3.Request;
+import okhttp3.Response;
+
+import java.io.IOException;
+import java.lang.reflect.Method;
+import java.util.List;
+import java.util.function.BiFunction;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+import static java.util.stream.Collectors.toList;
+import static java.util.stream.StreamSupport.stream;
+
+@NonNullApi
+@NonNullFields
+public class DefaultOkHttpKeyValuesProvider implements OkHttpKeyValuesProvider {
+
+    static final boolean REQUEST_TAG_CLASS_EXISTS;
+
+    static {
+        REQUEST_TAG_CLASS_EXISTS = getMethod(Class.class) != null;
+    }
+
+    @Nullable
+    private static Method getMethod(Class<?>... parameterTypes) {
+        try {
+            return Request.class.getMethod("tag", parameterTypes);
+        }
+        catch (NoSuchMethodException e) {
+            return null;
+        }
+    }
+
+    private static final String TAG_TARGET_SCHEME = "target.scheme";
+
+    private static final String TAG_TARGET_HOST = "target.host";
+
+    private static final String TAG_TARGET_PORT = "target.port";
+
+    private static final String TAG_VALUE_UNKNOWN = "UNKNOWN";
+
+    private static final KeyValues TAGS_TARGET_UNKNOWN = KeyValues.of(TAG_TARGET_SCHEME, TAG_VALUE_UNKNOWN,
+            TAG_TARGET_HOST, TAG_VALUE_UNKNOWN, TAG_TARGET_PORT, TAG_VALUE_UNKNOWN);
+
+    @Override
+    public KeyValues getLowCardinalityKeyValues(OkHttpContext context) {
+        OkHttpMetricsEventListener.CallState state = context.getState();
+        Request request = state.request;
+        boolean requestAvailable = request != null;
+        Function<Request, String> urlMapper = context.getUrlMapper();
+        Iterable<Tag> extraTags = context.getExtraTags();
+        Iterable<BiFunction<Request, Response, Tag>> contextSpecificTags = context.getContextSpecificTags();
+        Iterable<Tag> unknownRequestTags = context.getUnknownRequestTags();
+        boolean includeHostTag = context.isIncludeHostTag();
+        KeyValues keyValues = KeyValues.of("method", requestAvailable ? request.method() : TAG_VALUE_UNKNOWN, "uri",
+                getUriTag(urlMapper, state, request), "status", getStatusMessage(state.response, state.exception))
+                .and(tagsToKeyValues(stream(extraTags.spliterator(), false)))
+                .and(stream(contextSpecificTags.spliterator(), false)
+                        .map(contextTag -> contextTag.apply(request, state.response))
+                        .map(tag -> KeyValue.of(tag.getKey(), tag.getValue())).collect(toList()))
+                .and(getRequestTags(request, tagsToKeyValues(stream(unknownRequestTags.spliterator(), false))))
+                .and(generateTagsForRoute(request));
+        if (includeHostTag) {
+            keyValues = KeyValues.of(keyValues).and("host",
+                    requestAvailable ? request.url().host() : TAG_VALUE_UNKNOWN);
+        }
+        return keyValues;
+    }
+
+    private String getUriTag(Function<Request, String> urlMapper, OkHttpMetricsEventListener.CallState state,
+            @Nullable Request request) {
+        if (request == null) {
+            return TAG_VALUE_UNKNOWN;
+        }
+        return state.response != null && (state.response.code() == 404 || state.response.code() == 301) ? "NOT_FOUND"
+                : urlMapper.apply(request);
+    }
+
+    private String getStatusMessage(@Nullable Response response, @Nullable IOException exception) {
+        if (exception != null) {
+            return "IO_ERROR";
+        }
+
+        if (response == null) {
+            return "CLIENT_ERROR";
+        }
+
+        return Integer.toString(response.code());
+    }
+
+    private Iterable<KeyValue> getRequestTags(@Nullable Request request, Iterable<KeyValue> unknownRequestTags) {
+        if (request == null) {
+            return unknownRequestTags;
+        }
+        if (REQUEST_TAG_CLASS_EXISTS) {
+            Tags requestTag = request.tag(Tags.class);
+            if (requestTag != null) {
+                return tagsToKeyValues(requestTag.stream());
+            }
+        }
+        Object requestTag = request.tag();
+        if (requestTag instanceof Tags) {
+            return tagsToKeyValues(((Tags) requestTag).stream());
+        }
+        return KeyValues.empty();
+    }
+
+    private List<KeyValue> tagsToKeyValues(Stream<Tag> requestTag) {
+        return requestTag.map(tag -> KeyValue.of(tag.getKey(), tag.getValue())).collect(Collectors.toList());
+    }
+
+    private KeyValues generateTagsForRoute(@Nullable Request request) {
+        if (request == null) {
+            return TAGS_TARGET_UNKNOWN;
+        }
+        return KeyValues.of(TAG_TARGET_SCHEME, request.url().scheme(), TAG_TARGET_HOST, request.url().host(),
+                TAG_TARGET_PORT, Integer.toString(request.url().port()));
+    }
+
+}