docs(instrumentation): add telemetry descriptions for httpurlconnection, okhttp3 and okhttp3-websocket (Issue #742) (#1242)

* docs(instrumentation/httpurlconnection): add telemetry section to README and align structure with slowrendering/startup style

* docs(instrumentation/okhttp3): add telemetry section to README

* docs(instrumentation/okhttp3-websocket): add telemetry section to README

* Apply suggestions from code review

Co-authored-by: jason plumb <[email protected]>

---------

Co-authored-by: jason plumb <[email protected]>

Author: marcschaeferger

instrumentation/httpurlconnection/README.md

@@ -1,33 +1,86 @@
 # Android Instrumentation for URLConnection, HttpURLConnection and HttpsURLConnection
 
-## Status : Experimental
+Status: development
+
+The OpenTelemetry HttpUrlConnection instrumentation for Android will automatically
+instrument client-side usage of:
 
-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)
 
+The instrumentation operates by intercepting application calls to the APIs that
+initiate or read from network connections. It performs three primary actions:
+
+- adds distributed tracing context to outgoing requests
+- creates and ends client HTTP spans
+- records request/response metadata and exceptions
+
+[See the Android URLConnection documentation](https://developer.android.com/reference/java/net/URLConnection) for reference.
+
+## Telemetry
+
+This instrumentation produces HTTP client spans using the OpenTelemetry HTTP semantic
+conventions. The instrumentation scope (instrumentation library name) is
+`io.opentelemetry.android.http-url-connection`.
+
+### HTTP client span
+
+This instrumentation creates a span for each HTTP request. Spans are ended when one of
+the following occurs: the response stream is fully read, the stream is closed,
+`disconnect()` is called, or an exception occurs while interacting with the connection.
+
+- Type: Span
+- Name: Determined by the HTTP span name extractor (typically `HTTP {method}` or derived from the URL)
+- Description: Client-side HTTP request
+- Attributes (following OpenTelemetry [HTTP semantic conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/)):
+  - `http.method` — request method (GET, POST, etc.)
+  - `http.url` — full URL
+  - `http.target`, `http.host`, `http.scheme` — parts of the request URL when available
+  - `http.status_code` — response status code
+  - `http.flavor` — protocol (e.g. `1.1`)
+  - `net.peer.name` — server host
+  - `net.peer.port` — server port
+  - Request and response headers captured according to configuration: `http.request.header.*` / `http.response.header.*`
+
+If the request throws an IOException, the span is ended and the exception is recorded.
+
+### Configuration impact on telemetry
+
+You can customize which request and response headers are captured and other behavior via
+the `HttpUrlInstrumentation` setters exposed through `AndroidInstrumentationLoader`.
+These settings are applied when `HttpUrlConnectionSingletons.configure(...)` is called
+during instrumentation setup. See the `Configurations` section above for how to access
+the instrumentation instance.
+
+### Distributed tracing propagation
+
+The instrumentation injects the configured context propagators into the request using
+request properties (via a TextMap setter), allowing distributed tracing across services.
+
 ## 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 and ends/reports any open spans associated with them. Idle connections are those that have been read from previously but have been inactive for a particular configurable time interval (defaults to 10 seconds).
 
 > The minimum supported Android SDK version is 21, though it will also instrument APIs added in the Android SDK version 26 when running on devices with API level 26 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).
 >
 > Further, 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`
 >
@@ -61,6 +114,7 @@ byteBuddy("io.opentelemetry.android.instrumentation:httpurlconnection-agent:0.15
 #### Scheduling Harvester Thread
 
 To schedule a periodically running thread to conclude/report 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
 HttpUrlInstrumentation instrumentation = AndroidInstrumentationLoader.getInstrumentation(HttpUrlInstrumentation.class);
 instrumentation.setConnectionInactivityTimeoutMs(customTimeoutValue); //This is optional. Replace customTimeoutValue with a long data type value which denotes the connection inactivity timeout in milli seconds. Defaults to 10000ms
@@ -72,6 +126,7 @@ Executors.newSingleThreadScheduledExecutor().scheduleWithFixedDelay(instrumentat
 - It is efficient to run the harvester thread at the same time interval as the connection inactivity timeout used to identify the connections to be reported. `instrumentation.getReportIdleConnectionInterval()` is the API to get the same connection inactivity timeout interval (milliseconds) you have configured or the default value of 10000ms if not configured.
 
 #### Other Optional Configurations
+
 You can optionally configure the automatic instrumentation by using the setters from [HttpUrlInstrumentation](library/src/main/java/io/opentelemetry/instrumentation/library/httpurlconnection/HttpUrlInstrumentation.kt)
 instance provided via the AndroidInstrumentationLoader as shown below:
 

instrumentation/okhttp3-websocket/README.md

@@ -1,9 +1,30 @@
 # Android Instrumentation for OkHttp Websocket version 3.0 and higher
 
-## Status: development
+Status: development
+
+The OpenTelemetry OkHttp WebSocket instrumentation for Android instruments
+client-side OkHttp WebSocket usage. It creates telemetry for websocket lifecycle
+events and can capture metadata about connections and messages.
 
 Provides OpenTelemetry instrumentation for [okhttp3 websockets](https://square.github.io/okhttp/3.x/okhttp/okhttp3/WebSocket.html).
 
+## Telemetry
+
+This instrumentation primarily produces events/spans related to the WebSocket
+connection lifecycle (connect, close, errors) and can record attributes such as
+the peer host/port and any configured headers.
+
+* Type: Span / Event (connection lifecycle)
+* Name: Determined by instrumentation (e.g. `WebSocket connect` / `WebSocket close`)
+* Attributes (examples):
+  * `net.peer.name` — server host
+  * `net.peer.port` — server port
+  * `http.url` — the websocket URL
+  * Captured headers per configuration
+
+If a websocket connection errors, the instrumentation records the error on the
+connection telemetry.
+
 ## Installation
 
 ### Applying the Byte Buddy plugin

instrumentation/okhttp3/README.md

@@ -1,8 +1,32 @@
 # Android Instrumentation for OkHttp version 3.0 and higher
 
-## Status: development
+Status: development
 
-Provides OpenTelemetry instrumentation for [okhttp3](https://square.github.io/okhttp/).
+The OpenTelemetry OkHttp instrumentation for Android instruments client-side requests
+made via OkHttp (version 3.0 +) [okhttp3](https://square.github.io/okhttp/). It adds distributed tracing context,
+creates client HTTP spans, and records request/response metadata.
+
+## Telemetry
+
+This instrumentation produces HTTP client spans using the OpenTelemetry [HTTP semantic
+conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/). The span name is created via the HTTP span name extractor and attributes
+are provided by the OkHttp attributes getter.
+
+### HTTP client span
+
+* Type: Span
+* Name: Determined by the HTTP span name extractor (typically `HTTP {method}` or derived from the URL)
+* Description: Client-side HTTP request
+* Common attributes (following OpenTelemetry HTTP semantic conventions):
+  * `http.method` — request method (GET, POST, etc.)
+  * `http.url` — full URL
+  * `http.status_code` — response status code
+  * `http.flavor` — protocol (e.g. `1.1`)
+  * `net.peer.name` — server host
+  * `net.peer.port` — server port
+  * Captured request/response headers per configuration
+
+If a request fails, the span is ended and the error is recorded.
 
 ## Quickstart