OkHttp3 library enhancement for gathering network phases timing via HTTP Span Events #14835
Description
Is your feature request related to a problem? Please describe.
Current OkHttp3 instrumentation only captures total request duration. Performance issues appear as generic "slow requests" without identifying specific bottlenecks (DNS resolution, TLS handshake, server processing, etc.). OkHttp's EventListener provides perfect hooks for all network phases but isn't currently utilized.
Describe the solution you'd like
Enhance the existing OkHttp instrumentation to capture granular network timing phases as HTTP span events using OkHttp's EventListener API. This provides detailed timing breakdown (DNS, TCP, TLS, request/response phases) within HTTP spans for performance analysis.
| OkHttp EventListener Method | Proposed Span Event | Description |
|---|---|---|
| dnsStart() | http.dns.start | DNS resolution begins |
| dnsEnd() | http.dns.end | DNS resolution completes |
| connectStart() | http.connection.start | TCP connection establishment begins |
| connectEnd() | http.connection.end | TCP connection establishment completes |
| secureConnectStart() | http.tls.start | TLS handshake begins (HTTPS only) |
| secureConnectEnd() | http.tls.end | TLS handshake completes (HTTPS only) |
| requestHeadersStart() | http.request.header.start | Request headers transmission begins |
| requestHeadersEnd() | http.request.header.end | Request headers transmission completes |
| requestBodyStart() | http.request.body.start | Request body upload begins |
| requestBodyEnd() | http.request.body.end | Request body upload completes |
| responseHeadersStart() | http.response.header.start | Response headers reception begins |
| responseHeadersEnd() | http.response.header.end | Response headers reception completes |
| responseBodyStart() | http.response.body.start | Response body download begins |
| responseBodyEnd() | http.response.body.end | Response body download completes |
Additional callouts:
- These events would be optional and controlled via a boolean configuration flag (false by default) in OkHttpTelemetryBuilder.
- Event names and attributes follow the proposed HTTP span events semantic conventions in opentelemetry/semantic-conventions repo (pending approval).
This enhancement transforms OkHttp spans from basic request timing to comprehensive network performance analysis, enabling actionable insights for application performance optimization.
Describe alternatives you've considered
- OpenTelemetry's existing metric signals cannot address these requirements due to their aggregated nature and inability to preserve request-level timing correlation.
- The proposal to deprecate span events in favor of standalone events will take time to take effect / be adopted and in the interim the proposed solution will help and it can later be migrated to standalone events as needed.
Additional context
No response
Tip
React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.