open-telemetry / open-telemetry/opentelemetry-java-instrumentation
OkHttp3 library enhancement for gathering network phases timing via HTTP Span Events
@surbhiia is already working on this.
Since Sep 30, 2025.
- Dominant language
- Java
- Stars
- 2.6k
- Forks
- 1.2k
- Avg merge
- 2d 18h
- Merged PRs (30d)
- 228
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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.