Add HTTP span events for network phases breakdown

[surbhiia]

Area(s)

area:http

What's missing?

Currently, OpenTelemetry Client HTTP instrumentations (such as OkHttp3) do not capture granular network phase timing, missing critical timed events like DNS resolution start/end, TLS handshake start/end, and TCP connection establishment start/end timestamps. When captured as span events, this detailed timing data would enable observability backends to identify specific performance bottlenecks (DNS latency, TLS negotiation delays, connection issues) within individual HTTP requests and implement their own metric aggregation strategies (P95 DNS time, TLS success rates etc) tailored to their analytical needs. OpenTelemetry's existing metric signals cannot address these requirements due to their aggregated nature and inability to preserve request-level timing correlation.

Describe the solution you'd like

Capture the relevant events as span events.

Proposing event names (as per naming guidelines) to be captured as span events for client HTTP spans (Span name and timestamp matters the most, no additional attributes needed as span attributes are enough)

Event Name	Description	Timing Phase	Required
http.dns.start	DNS resolution begins	Network Setup	Optional
http.dns.end	DNS resolution completes	Network Setup	Optional
http.connection.start	TCP connection establishment begins	Connection Phase	Optional
http.connection.end	TCP connection establishment completes	Connection Phase	Optional
http.tls.start	TLS handshake begins (HTTPS only)	Security Phase	Optional
http.tls.end	TLS handshake completes (HTTPS only)	Security Phase	Optional
http.request.header.start	Request headers transmission begins	Request Phase	Optional
http.request.header.end	Request headers transmission completes	Request Phase	Optional
http.request.body.start	Request body upload begins	Request Phase	Optional
http.request.body.end	Request body upload completes	Request Phase	Optional
http.response.header.start	Response headers reception begins	Response Phase	Optional
http.response.header.end	Response headers reception completes	Response Phase	Optional
http.response.body.start	Response body download begins	Response Phase	Optional
http.response.body.end	Response body download completes	Response Phase	Optional

Example metrics / granular breakdown per request that these events help observability backends gather:

Metrics	Calculation
DNS Resolution Duration	http.dns.end.timestamp - http.dns.start.timestamp
TCP Connection Duration	http.connection.end.timestamp - http.connection.start.timestamp
TLS Handshake Duration	http.tls.end.timestamp - http.tls.start.timestamp
Network Setup Duration	http.connection.end.timestamp - http.dns.start.timestamp
Request Header Transmission Duration	http.request.header.end.timestamp - http.request.header.start.timestamp
Request Body Upload Duration	http.request.body.end.timestamp - http.request.body.start.timestamp
Total Request Transmission Duration	http.request.body.end.timestamp - http.request.header.start.timestamp
Response Header Reception Duration	http.response.header.end.timestamp - http.response.header.start.timestamp
Response Body Download Duration	http.response.body.end.timestamp - http.response.body.start.timestamp
Total Response Reception Duration	http.response.body.end.timestamp - http.response.header.start.timestamp
Total Network Transfer Duration	http.response.body.end.timestamp - http.request.header.start.timestamp
Time to First Byte (TTFB) / Server Processing Duration	http.response.header.start.timestamp - http.request.body.end.timestamp
Time to Last Byte (TTLB)	http.response.body.end.timestamp - http.request.body.end.timestamp

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.}

[thompson-tomo]

I feel the proposal is being overly verbose in the events being defined and instead should be grouped/reduced

For dns queries why aren't we using the dns.lookup.duration metric? Why are we not using the dns query span to capture duration? https://opentelemetry.io/docs/specs/semconv/dotnet/dotnet-network-traces/#dns-lookup

For tls handshake the metric should be in the tls namespace? why are we not using the tls span https://opentelemetry.io/docs/specs/semconv/dotnet/dotnet-network-traces/#tls-handshake

Similar for connection setup we should be using the https://opentelemetry.io/docs/specs/semconv/dotnet/dotnet-network-traces/#http-connection-setup span.

In relation to Events for processing http parts we could have a single event and use attributes to differentiate them similar to the browser web_vital events and also simplify the metrics in a similar fashion.

[ladd]

I agree that durations are sufficient. However, there is some value in making these events rather than spans. Analytics pipelines will typically have an easier time reading events attached to a span, rather than trying to join across spans. (obviously depends on how trace storage is implemented, but this is what I've seen).

[thompson-tomo]

So the transformation to metrics should be done in the collector rather than the trace storage.

I would still use events to understand the timing of the http parts ie request body start but ideally consolidate the number of definitions by using attributes

[ladd]

Regardless of where metric transformation happens, it's easier to achieve if you're not joining across spans, since they're not guaranteed to be delivered in the same payload. Although conceptually these could be represented as spans, using an event named http.dns with an attribute duration would achieve the goal, I think, given that events have timestamps.

You could also simply attach duration attributes directly to the HTTP span, given that there's not a ton of value in knowing when each phase occurred. They have a pre-determined order, due to the protocol design.

[thompson-tomo]

Not seeing where you are getting joining across spans from given that I am only talking about using spans for dns, tls & http connection which is already defined. For the metrics these spans would be a one to one mapping to the metric. There would still be events for the different parts of the message

[surbhiia]

A few things I am gathering from the discussions so far are:

• Connection-level operations (DNS, CONNECT, TLS) are better are separate spans as they're not directly tied to each request. They may/ may not be related to the original HTTP span which triggered them. And that's okay as metrics are derived on them separately and not with relation to each request.
• Request-specific operations (like headers, body transmission) are tied to the HTTP request and are acceptable as standalone events which contain context (traceId, spanId) of the original HTTP span (as there are plans to deprecate span.events). And we need to define them properly to reduce the number of events / attributes emitted - possibly one event with all the details needed.

Some questions based on above

• Are there use cases requiring DNS, CONNECT, TLS spans to be linked to the original HTTP span which triggered them?
• For request specific operations, can backends process the standalone event (with trace context to original HTTP span) for their metric requirement or do they instead require links from the original HTTP span to the event?
• Should we emit:
  -- Option A: Raw Timestamp Attributes - Provide granular start/end timestamps as attributes in one event(A.1) or attributes in original HTTP span (A.2) (e.g., http.request.header.start, http.request.header.end, http.response.body.start, http.response.body.end) allowing backends to calculate any duration metrics they need? OR
  -- Option B: Pre-calculated Duration Attributes - Select key metrics from our metric proposal table and emit them as duration attributes directly on the HTTP span (e.g., http.client.server_processing.duration)?

[thompson-tomo]

Are there use cases requiring DNS, CONNECT, TLS spans to be linked to the original HTTP span which triggered them?

Ideally the dns span would be a child span of the http hence enabling the linking.

I would propose an option c:

• A http.{client|server}.data.processed event which contains the following attributes network.io.direction, http.data.locationie header/body &event.elapsedorevent.duration` for how long it took.

[surbhiia]

@thompson-tomo Would you know what would be the relevant semantic convention SIG meeting to bring this up in -> Mon - Semantic Convention WG or Tue - OpenTelemetry Specification SIG + Maintainers Sync or any other meeting from this calendar? Thanks!