Http/sURLConnection auto instrumentation

gradle/libs.versions.toml

@@ -20,15 +20,16 @@ androidx-core = "androidx.core:core:1.13.1"
 findbugs-jsr305 = "com.google.code.findbugs:jsr305:3.0.2"
 byteBuddy = { module = "net.bytebuddy:byte-buddy", version.ref = "byteBuddy" }
 okhttp = { module = "com.squareup.okhttp3:okhttp", version.ref = "okhttp" }
-opentelemetry-instrumentation-api = { module = "io.opentelemetry.instrumentation:opentelemetry-instrumentation-api" }
-opentelemetry-instrumentation-apiSemconv = { module = "io.opentelemetry.instrumentation:opentelemetry-instrumentation-api-incubator" }
+opentelemetry-instrumentation-api = { module = "io.opentelemetry.instrumentation:opentelemetry-instrumentation-api"}
+opentelemetry-instrumentation-apiSemconv = { module = "io.opentelemetry.instrumentation:opentelemetry-instrumentation-api-incubator", version.ref = "opentelemetry-instrumentation-alpha"}
 opentelemetry-instrumentation-okhttp = { module = "io.opentelemetry.instrumentation:opentelemetry-okhttp-3.0", version.ref = "opentelemetry-instrumentation-alpha" }
 opentelemetry-semconv = { module = "io.opentelemetry.semconv:opentelemetry-semconv", version.ref = "opentelemetry-semconv" }
 opentelemetry-semconv-incubating = { module = "io.opentelemetry.semconv:opentelemetry-semconv-incubating", version.ref = "opentelemetry-semconv" }
-opentelemetry-api = { module = "io.opentelemetry:opentelemetry-api" }
+opentelemetry-api = { module = "io.opentelemetry:opentelemetry-api"}
 opentelemetry-api-incubator = { module = "io.opentelemetry:opentelemetry-api-incubator" }
 opentelemetry-sdk-extension-incubator = { module = "io.opentelemetry:opentelemetry-sdk-extension-incubator", version.ref = "opentelemetry-alpha" }
-opentelemetry-sdk = { module = "io.opentelemetry:opentelemetry-sdk" }
+opentelemetry-sdk = { module = "io.opentelemetry:opentelemetry-sdk"}
+opentelemetry-context = { module = "io.opentelemetry:opentelemetry-context", version.ref = "opentelemetry"}
 opentelemetry-exporter-logging = { module = "io.opentelemetry:opentelemetry-exporter-logging" }
 opentelemetry-diskBuffering = { module = "io.opentelemetry.contrib:opentelemetry-disk-buffering", version.ref = "opentelemetry-contrib" }
 opentelemetry-exporter-otlp = { module = "io.opentelemetry:opentelemetry-exporter-otlp", version.ref = "opentelemetry" }

instrumentation/httpurlconnection/README.md

@@ -0,0 +1,75 @@
+# Android Instrumentation for URLConnection, HttpURLConnection and HttpsURLConnection
+
+## Status : Experimental
+
+Provides OpenTelemetry instrumentation for:
+- [URLConnection](https://developer.android.com/reference/java/net/URLConnection)
+- [HttpURLConnection](https://developer.android.com/reference/java/net/HttpURLConnection)
+- [HttpsURLConnection](https://developer.android.com/reference/javax/net/ssl/HttpsURLConnection)
+
+## Quickstart
+
+### Overview
+
+This plugin enhances the Android application host code by instrumenting all critical APIs (specifically those that initiate a connection). It intercepts calls to these APIs to ensure the following actions are performed:
+- Context is added for distributed tracing before actual API is called (i.e before connection is initiated).
+- Traces and spans are generated and properly closed.
+- Any exceptions thrown are recorded.
+
+A span associated with a given request is concluded in the following scenarios:
+- When the getInputStream()/getErrorStream() APIs are called, the span concludes after the stream is fully read, an IOException is encountered, or the stream is closed.
+- When the disconnect API is called.
+
+Spans won't be automatically ended and reported otherwise. If any of your URLConnection requests do not call the span concluding APIs mentioned above, refer the section entitled ["Scheduling Harvester Thread"](#scheduling-harvester-thread). This section provides guidance on setting up a recurring thread that identifies unreported, idle connections (those that have been read from but have been inactive for more than 10 seconds) and concludes any open spans associated with them.
+
+> The minimum supported Android SDK version is 21, though it will also instrument APIs added in the Android SDK version 24 when running on devices with API level 24 and above.
+
+> If your project's minSdk is lower than 26, then you must enable
+> [corelib desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring).
+>
+> If your project's minSdk is lower than 24, in order to run the app built on debug, you need to add the following property in `gradle.properties` file:
+> -  If AGP <= 8.3.0, set `android.enableDexingArtifactTransform=false`
+> - if AGP > 8.3.0, set `android.useFullClasspathForDexingTransform=true`
+>
+> For the full context for these workaround, please see
+> [this issue](https://issuetracker.google.com/issues/334281968) for AGP <= 8.3.0
+> or [this issue](https://issuetracker.google.com/issues/230454566#comment18) for AGP > 8.3.0.
+
+### Add these dependencies to your project
+
+Replace `AUTO_HTTP_URL_INSTRUMENTATION_VERSION` with the [latest release](https://central.sonatype.com/search?q=g%3Aio.opentelemetry.android++a%3Ahttpurlconnection-library&smo=true).
+
+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 [Transform API](https://developer.android.com/reference/tools/gradle-api/current/com/android/build/api/variant/ScopedArtifactsOperation#toTransform(com.android.build.api.artifact.ScopedArtifact,kotlin.Function1,kotlin.Function1,kotlin.Function1)) 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
+
+```kotlin
+implementation("io.opentelemetry.android:httpurlconnection-library:AUTO_HTTP_URL_INSTRUMENTATION_VERSION")
+byteBuddy("io.opentelemetry.android:httpurlconnection-agent:AUTO_HTTP_URL_INSTRUMENTATION_VERSION")
+```
+
+### Configurations
+
+#### Scheduling Harvester Thread
+
+To schedule a periodically running thread to conclude spans on any unreported, idle connections, add the below code in the function where your application starts ( that could be onCreate() method of first Activity/Fragment/Service):
+```Java
+Executors.newSingleThreadScheduledExecutor().scheduleWithFixedDelay(HttpUrlInstrumentationConfig.getReportIdleConnectionRunnable(), 0, HttpUrlInstrumentationConfig.getReportIdleConnectionInterval(), TimeUnit.MILLISECONDS);
+```
+
+`HttpUrlInstrumentationConfig.getReportIdleConnectionRunnable()` is the API to get the runnable. `HttpUrlInstrumentationConfig.getReportIdleConnectionInterval()` is the API to get the fixed interval (10s) in milli seconds.
+
+#### Other Optional Configurations
+You can optionally configure the automatic instrumentation by using the setters in [HttpUrlInstrumentationConfig](library/src/main/java/io/opentelemetry/instrumentation/library/httpurlconnection/HttpUrlInstrumentationConfig.java).
+
+After adding the plugin and the dependencies to your project, and after doing the required configurations, your requests will be traced automatically.

instrumentation/httpurlconnection/agent/build.gradle.kts

@@ -0,0 +1,15 @@
+plugins {
+    id("otel.android-library-conventions")
+    id("otel.publish-conventions")
+}
+
+description = "OpenTelemetry build-time auto-instrumentation for HttpURLConnection on Android"
+
+android {
+    namespace = "io.opentelemetry.android.httpurlconnection.agent"
+}
+
+dependencies {
+    implementation(project(":instrumentation:httpurlconnection:library"))
+    implementation(libs.byteBuddy)
+}