Adding okhttp autoinstrumentation

auto-instrumentation/okhttp/okhttp-3.0/README.md

@@ -0,0 +1,41 @@
+# Android Instrumentation for OkHttp version 3.0 and higher
+
+Provides OpenTelemetry instrumentation for [okhttp3](https://square.github.io/okhttp/).
+
+## Quickstart
+
+### Add these dependencies to your project
+
+Replace `OPENTELEMETRY_VERSION` with the [latest
+release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-okhttp-3.0).
+
+Replace `BYTEBUDDY_VERSION` with the [latest
+release](https://search.maven.org/search?q=g:net.bytebuddy%20AND%20a:byte-buddy).
+
+#### Byte buddy compilation plugin
+
+This plugin leverages
+Android's [ASM API](https://developer.android.com/reference/tools/gradle-api/8.0/com/android/build/api/instrumentation/AsmClassVisitorFactory)
+to instrument bytecode at compile time. You can find more info on
+its [repo page](https://github.com/raphw/byte-buddy/tree/master/byte-buddy-gradle-plugin/android-plugin.
+
+```groovy
+plugins {
+    id 'net.bytebuddy.byte-buddy-gradle-plugin' version 'BYTEBUDDY_VERSION'
+}
+```
+
+#### Project dependencies
+
+```groovy
+implementation "io.opentelemetry.android:okhttp-3.0-library:OPENTELEMETRY_VERSION"
+byteBuddy "io.opentelemetry.android:okhttp-3.0-agent:OPENTELEMETRY_VERSION"
+```
+
+After adding the plugin and the dependencies in your project, you'll automatically get your OkHttp
+requests traced.
+
+### Configuration
+
+You can configure the automatic instrumentation by using the setters
+in [OkHttpInstrumentationConfig](library/src/main/java/io/opentelemetry/instrumentation/library/okhttp/v3_0/OkHttpInstrumentationConfig.java)).

auto-instrumentation/okhttp/okhttp-3.0/agent/build.gradle.kts

@@ -0,0 +1,9 @@
+plugins {
+    id("otel.java-library-conventions")
+    id("otel.publish-conventions")
+}
+
+dependencies {
+    implementation(project(":auto-instrumentation:okhttp:okhttp-3.0:library"))
+    implementation("net.bytebuddy:byte-buddy:${property("bytebuddy.version")}")
+}

auto-instrumentation/okhttp/okhttp-3.0/agent/src/main/java/io/opentelemetry/instrumentation/agent/okhttp/v3_0/OkHttpClientAdvice.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.agent.okhttp.v3_0;
+
+import io.opentelemetry.instrumentation.library.okhttp.v3_0.internal.OkHttp3Singletons;
+import net.bytebuddy.asm.Advice;
+import okhttp3.OkHttpClient;
+
+public class OkHttpClientAdvice {
+
+    @Advice.OnMethodEnter
+    public static void enter(@Advice.Argument(0) OkHttpClient.Builder builder) {
+        if (!builder.interceptors().contains(OkHttp3Singletons.CONTEXT_INTERCEPTOR)) {
+            builder.interceptors().add(0, OkHttp3Singletons.CONTEXT_INTERCEPTOR);
+            builder.interceptors().add(1, OkHttp3Singletons.CONNECTION_ERROR_INTERCEPTOR);
+        }
+        if (!builder.networkInterceptors().contains(OkHttp3Singletons.TRACING_INTERCEPTOR)) {
+            builder.addNetworkInterceptor(OkHttp3Singletons.TRACING_INTERCEPTOR);
+        }
+    }
+}

auto-instrumentation/okhttp/okhttp-3.0/agent/src/main/java/io/opentelemetry/instrumentation/agent/okhttp/v3_0/OkHttpClientPlugin.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.agent.okhttp.v3_0;
+
+import java.io.IOException;
+import net.bytebuddy.asm.Advice;
+import net.bytebuddy.build.Plugin;
+import net.bytebuddy.description.type.TypeDescription;
+import net.bytebuddy.dynamic.ClassFileLocator;
+import net.bytebuddy.dynamic.DynamicType;
+import net.bytebuddy.matcher.ElementMatchers;
+import okhttp3.OkHttpClient;
+
+public class OkHttpClientPlugin implements Plugin {
+
+    @Override
+    public DynamicType.Builder<?> apply(
+            DynamicType.Builder<?> builder,
+            TypeDescription typeDescription,
+            ClassFileLocator classFileLocator) {
+        return builder.visit(
+                Advice.to(OkHttpClientAdvice.class)
+                        .on(
+                                ElementMatchers.isConstructor()
+                                        .and(
+                                                ElementMatchers.takesArguments(
+                                                        OkHttpClient.Builder.class))));
+    }
+
+    @Override
+    public void close() throws IOException {
+        // No operation.
+    }
+
+    @Override
+    public boolean matches(TypeDescription target) {
+        return target.getTypeName().equals("okhttp3.OkHttpClient");
+    }
+}

auto-instrumentation/okhttp/okhttp-3.0/agent/src/main/resources/META-INF/net.bytebuddy/build.plugins

@@ -0,0 +1 @@
+io.opentelemetry.instrumentation.agent.okhttp.v3_0.OkHttpClientPlugin

auto-instrumentation/okhttp/okhttp-3.0/library/build.gradle.kts

@@ -0,0 +1,11 @@
+plugins {
+    id("otel.java-library-conventions")
+    id("otel.publish-conventions")
+}
+
+val otelVersion = project.property("otel.sdk.version")
+dependencies {
+    api("com.squareup.okhttp3:okhttp:3.0.0")
+    api("io.opentelemetry.instrumentation:opentelemetry-okhttp-3.0:$otelVersion-alpha")
+    implementation("io.opentelemetry.instrumentation:opentelemetry-instrumentation-api-semconv:$otelVersion-alpha")
+}

auto-instrumentation/okhttp/okhttp-3.0/library/src/main/java/io/opentelemetry/instrumentation/library/okhttp/v3_0/OkHttpInstrumentationConfig.java

@@ -0,0 +1,121 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.library.okhttp.v3_0;
+
+import io.opentelemetry.instrumentation.api.internal.HttpConstants;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import javax.annotation.Nonnull;
+
+/** Configuration for automatic instrumentation of okhttp requests. */
+public final class OkHttpInstrumentationConfig {
+    private static List<String> capturedRequestHeaders = new ArrayList<>();
+    private static List<String> capturedResponseHeaders = new ArrayList<>();
+    private static Set<String> knownMethods = new HashSet<>();
+    private static Map<String, String> peerServiceMapping = new HashMap<>();
+    private static boolean emitExperimentalHttpClientMetrics;
+
+    private OkHttpInstrumentationConfig() {}
+
+    /**
+     * Configures the HTTP request headers that will be captured as span attributes as described in
+     * <a
+     * href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md#http-request-and-response-headers">HTTP
+     * semantic conventions</a>.
+     *
+     * <p>The HTTP request header values will be captured under the {@code
+     * http.request.header.<name>} attribute key. The {@code <name>} part in the attribute key is
+     * the normalized header name: lowercase, with dashes replaced by underscores.
+     *
+     * @param requestHeaders A list of HTTP header names.
+     */
+    public static void setCapturedRequestHeaders(@Nonnull List<String> requestHeaders) {
+        OkHttpInstrumentationConfig.capturedRequestHeaders = requestHeaders;
+    }
+
+    public static List<String> getCapturedRequestHeaders() {
+        return capturedRequestHeaders;
+    }
+
+    /**
+     * Configures the HTTP response headers that will be captured as span attributes as described in
+     * <a
+     * href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md#http-request-and-response-headers">HTTP
+     * semantic conventions</a>.
+     *
+     * <p>The HTTP response header values will be captured under the {@code
+     * http.response.header.<name>} attribute key. The {@code <name>} part in the attribute key is
+     * the normalized header name: lowercase, with dashes replaced by underscores.
+     *
+     * @param responseHeaders A list of HTTP header names.
+     */
+    public static void setCapturedResponseHeaders(@Nonnull List<String> responseHeaders) {
+        OkHttpInstrumentationConfig.capturedResponseHeaders = responseHeaders;
+    }
+
+    public static List<String> getCapturedResponseHeaders() {
+        return capturedResponseHeaders;
+    }
+
+    /**
+     * Configures the attrs extractor to recognize an alternative set of HTTP request methods.
+     *
+     * <p>By default, the extractor defines "known" methods as the ones listed in <a
+     * href="https://www.rfc-editor.org/rfc/rfc9110.html#name-methods">RFC9110</a> and the PATCH
+     * method defined in <a href="https://www.rfc-editor.org/rfc/rfc5789.html">RFC5789</a>. If an
+     * unknown method is encountered, the extractor will use the value {@value HttpConstants#_OTHER}
+     * instead of it and put the original value in an extra {@code http.request.method_original}
+     * attribute.
+     *
+     * <p>Note: calling this method <b>overrides</b> the default known method sets completely; it
+     * does not supplement it.
+     *
+     * @param knownMethods A set of recognized HTTP request methods.
+     */
+    public static void setKnownMethods(@Nonnull Set<String> knownMethods) {
+        OkHttpInstrumentationConfig.knownMethods = knownMethods;
+    }
+
+    public static Set<String> getKnownMethods() {
+        return knownMethods;
+    }
+
+    /**
+     * Configures the extractor of the {@code peer.service} span attribute, described in <a
+     * href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/span-general.md#general-remote-service-attributes">the
+     * specification</a>.
+     */
+    public static void setPeerServiceMapping(@Nonnull Map<String, String> peerServiceMapping) {
+        OkHttpInstrumentationConfig.peerServiceMapping = peerServiceMapping;
+    }
+
+    public static Map<String, String> getPeerServiceMapping() {
+        return peerServiceMapping;
+    }
+
+    /**
+     * When enabled keeps track of <a
+     * href="https://github.com/open-telemetry/semantic-conventions/blob/main/specification/metrics/semantic_conventions/http-metrics.md#http-client">non-stable
+     * HTTP client metrics</a>: <a
+     * href="https://github.com/open-telemetry/semantic-conventions/blob/main/specification/metrics/semantic_conventions/http-metrics.md#metric-httpclientrequestsize">the
+     * request size </a> and the <a
+     * href="https://github.com/open-telemetry/semantic-conventions/blob/main/specification/metrics/semantic_conventions/http-metrics.md#metric-httpclientresponsesize">
+     * the response size</a>.
+     */
+    public static void setEmitExperimentalHttpClientMetrics(
+            boolean emitExperimentalHttpClientMetrics) {
+        OkHttpInstrumentationConfig.emitExperimentalHttpClientMetrics =
+                emitExperimentalHttpClientMetrics;
+    }
+
+    public static boolean emitExperimentalHttpClientMetrics() {
+        return emitExperimentalHttpClientMetrics;
+    }
+}

auto-instrumentation/okhttp/okhttp-3.0/library/src/main/java/io/opentelemetry/instrumentation/library/okhttp/v3_0/internal/OkHttp3Singletons.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.library.okhttp.v3_0.internal;
+
+import static java.util.Collections.singletonList;
+
+import io.opentelemetry.api.GlobalOpenTelemetry;
+import io.opentelemetry.context.Context;
+import io.opentelemetry.context.Scope;
+import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
+import io.opentelemetry.instrumentation.api.instrumenter.http.HttpClientResend;
+import io.opentelemetry.instrumentation.api.instrumenter.net.PeerServiceAttributesExtractor;
+import io.opentelemetry.instrumentation.library.okhttp.v3_0.OkHttpInstrumentationConfig;
+import io.opentelemetry.instrumentation.okhttp.v3_0.internal.ConnectionErrorSpanInterceptor;
+import io.opentelemetry.instrumentation.okhttp.v3_0.internal.OkHttpAttributesGetter;
+import io.opentelemetry.instrumentation.okhttp.v3_0.internal.OkHttpInstrumenterFactory;
+import io.opentelemetry.instrumentation.okhttp.v3_0.internal.TracingInterceptor;
+import okhttp3.Interceptor;
+import okhttp3.Request;
+import okhttp3.Response;
+
+/** Holder of singleton interceptors for adding to instrumented clients. */
+public final class OkHttp3Singletons {
+
+    private static final Instrumenter<Request, Response> INSTRUMENTER =
+            OkHttpInstrumenterFactory.create(
+                    GlobalOpenTelemetry.get(),
+                    builder ->
+                            builder.setCapturedRequestHeaders(
+                                            OkHttpInstrumentationConfig.getCapturedRequestHeaders())
+                                    .setCapturedResponseHeaders(
+                                            OkHttpInstrumentationConfig
+                                                    .getCapturedResponseHeaders())
+                                    .setKnownMethods(OkHttpInstrumentationConfig.getKnownMethods()),
+                    singletonList(
+                            PeerServiceAttributesExtractor.create(
+                                    OkHttpAttributesGetter.INSTANCE,
+                                    OkHttpInstrumentationConfig.getPeerServiceMapping())),
+                    OkHttpInstrumentationConfig.emitExperimentalHttpClientMetrics());
+
+    public static final Interceptor CONTEXT_INTERCEPTOR =
+            chain -> {
+                try (Scope ignored = HttpClientResend.initialize(Context.current()).makeCurrent()) {
+                    return chain.proceed(chain.request());
+                }
+            };
+
+    public static final Interceptor CONNECTION_ERROR_INTERCEPTOR =
+            new ConnectionErrorSpanInterceptor(INSTRUMENTER);
+
+    public static final Interceptor TRACING_INTERCEPTOR =
+            new TracingInterceptor(INSTRUMENTER, GlobalOpenTelemetry.getPropagators());
+
+    private OkHttp3Singletons() {}
+}

auto-instrumentation/okhttp/okhttp-3.0/testing/build.gradle.kts

@@ -0,0 +1,11 @@
+plugins {
+    id("otel.android-app-conventions")
+    id("net.bytebuddy.byte-buddy-gradle-plugin")
+}
+
+dependencies {
+    byteBuddy(project(":auto-instrumentation:okhttp:okhttp-3.0:agent"))
+    implementation(project(":auto-instrumentation:okhttp:okhttp-3.0:library"))
+    implementation("com.squareup.okhttp3:okhttp:4.11.0")
+    androidTestImplementation("com.squareup.okhttp3:mockwebserver:4.11.0")
+}

auto-instrumentation/okhttp/okhttp-3.0/testing/src/androidTest/java/io/opentelemetry/instrumentation/library/okhttp/v3_0/InstrumentationTest.java

@@ -0,0 +1,66 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.library.okhttp.v3_0;
+
+import static org.junit.Assert.assertEquals;
+
+import androidx.annotation.NonNull;
+import io.opentelemetry.sdk.OpenTelemetrySdk;
+import io.opentelemetry.sdk.testing.exporter.InMemorySpanExporter;
+import io.opentelemetry.sdk.trace.SdkTracerProvider;
+import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor;
+import java.io.IOException;
+import okhttp3.OkHttpClient;
+import okhttp3.Request;
+import okhttp3.Response;
+import okhttp3.mockwebserver.MockResponse;
+import okhttp3.mockwebserver.MockWebServer;
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+
+public class InstrumentationTest {
+    private MockWebServer server;
+
+    @Before
+    public void setUp() throws IOException {
+        server = new MockWebServer();
+        server.start();
+    }
+
+    @After
+    public void tearDown() throws IOException {
+        server.shutdown();
+    }
+
+    @Test
+    public void okhttpTraces() throws IOException {
+        InMemorySpanExporter spanExporter = InMemorySpanExporter.create();
+        OpenTelemetrySdk.builder()
+                .setTracerProvider(getSimpleTracerProvider(spanExporter))
+                .buildAndRegisterGlobal();
+
+        server.enqueue(new MockResponse().setResponseCode(200));
+
+        OkHttpClient client = new OkHttpClient();
+        executeRequest(client, "/test/");
+
+        assertEquals(1, spanExporter.getFinishedSpanItems().size());
+    }
+
+    private void executeRequest(OkHttpClient client, String urlPath) throws IOException {
+        Request request = new Request.Builder().url(server.url(urlPath)).build();
+        Response response = client.newCall(request).execute();
+        response.body().bytes();
+    }
+
+    @NonNull
+    private static SdkTracerProvider getSimpleTracerProvider(InMemorySpanExporter spanExporter) {
+        return SdkTracerProvider.builder()
+                .addSpanProcessor(SimpleSpanProcessor.create(spanExporter))
+                .build();
+    }
+}