feat(contrib/net/http): add WithClientTimings option (#3839)

Co-authored-by: rarguelloF <rodrigo.arguello@datadoghq.com>
Co-authored-by: darccio <dario.castane@datadoghq.com>

Author: 3 people

contrib/net/http/example_test.go

@@ -7,6 +7,7 @@ package http_test
 
 import (
 	"net/http"
+	"net/http/httptest"
 
 	httptrace "github.com/DataDog/dd-trace-go/contrib/net/http/v2"
 	"github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
@@ -68,6 +69,40 @@ func ExampleWrapClient() {
 	http.ListenAndServe(":8080", mux)
 }
 
+// ExampleWrapClient_withClientTimings demonstrates how to enable detailed HTTP request tracing
+// using httptrace.ClientTrace. This provides timing information for DNS lookups, connection
+// establishment, TLS handshakes, and other HTTP request events as span tags.
+func ExampleWrapClient_withClientTimings() {
+	tracer.Start()
+	defer tracer.Stop()
+
+	// Create a test server for demonstration
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("OK"))
+	}))
+	defer server.Close()
+
+	// Create an HTTP client with ClientTimings enabled
+	c := httptrace.WrapClient(http.DefaultClient, httptrace.WithClientTimings(true))
+
+	// Make a request - the span will include detailed timing information
+	// such as http.dns.duration_ms, http.connect.duration_ms, etc.
+	req, _ := http.NewRequest(http.MethodGet, server.URL, nil)
+	resp, err := c.Do(req)
+	if err != nil {
+		return
+	}
+	defer resp.Body.Close()
+
+	// The resulting span will contain timing tags like:
+	// - http.dns.duration_ms: Time spent on DNS resolution
+	// - http.connect.duration_ms: Time spent establishing connection
+	// - http.tls.duration_ms: Time spent on TLS handshake
+	// - http.get_conn.duration_ms: Time spent getting connection from pool
+	// - http.first_byte.duration_ms: Time to first response byte
+}
+
 func traceMiddleware(mux *http.ServeMux, next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		_, route := mux.Handler(r)

contrib/net/http/internal/config/config.go

@@ -95,6 +95,7 @@ type RoundTripperConfig struct {
 	ErrCheck      func(err error) bool
 	QueryString   bool // reports whether the query string is included in the URL tag for http client spans
 	IsStatusError func(statusCode int) bool
+	ClientTimings bool // reports whether httptrace.ClientTrace should be enabled for detailed timing
 }
 
 func (c *RoundTripperConfig) ApplyOpts(opts ...RoundTripperOption) {

contrib/net/http/internal/wrap/roundtrip.go

@@ -6,23 +6,78 @@
 package wrap
 
 import (
+	"crypto/tls"
 	"fmt"
 	"math"
 	"net/http"
+	"net/http/httptrace"
 	"os"
 	"strconv"
+	"time"
 
 	"github.com/DataDog/dd-trace-go/contrib/net/http/v2/internal/config"
 	"github.com/DataDog/dd-trace-go/v2/appsec/events"
 	"github.com/DataDog/dd-trace-go/v2/ddtrace/baggage"
 	"github.com/DataDog/dd-trace-go/v2/ddtrace/ext"
 	"github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
 	"github.com/DataDog/dd-trace-go/v2/instrumentation/appsec/emitter/httpsec"
-	"github.com/DataDog/dd-trace-go/v2/instrumentation/httptrace"
+	instrumentationhttptrace "github.com/DataDog/dd-trace-go/v2/instrumentation/httptrace"
 )
 
 type AfterRoundTrip = func(*http.Response, error) (*http.Response, error)
 
+// httpTraceTimings captures key timing events from httptrace.ClientTrace
+type httpTraceTimings struct {
+	dnsStart, dnsEnd           time.Time
+	connectStart, connectEnd   time.Time
+	tlsStart, tlsEnd           time.Time
+	getConnStart, gotConn      time.Time
+	wroteHeaders, gotFirstByte time.Time
+	connectErr                 error
+	tlsErr                     error
+}
+
+// addDurationTag adds a timing tag to the span if both timestamps are valid
+func (t *httpTraceTimings) addDurationTag(span *tracer.Span, tagName string, start, end time.Time) {
+	if !start.IsZero() && !end.IsZero() {
+		duration := float64(end.Sub(start).Nanoseconds()) / 1e6
+		span.SetTag(tagName, duration)
+	}
+}
+
+// addTimingTags adds all timing information to the span
+func (t *httpTraceTimings) addTimingTags(span *tracer.Span) {
+	t.addDurationTag(span, "http.dns.duration_ms", t.dnsStart, t.dnsEnd)
+	t.addDurationTag(span, "http.connect.duration_ms", t.connectStart, t.connectEnd)
+	t.addDurationTag(span, "http.tls.duration_ms", t.tlsStart, t.tlsEnd)
+	t.addDurationTag(span, "http.get_conn.duration_ms", t.getConnStart, t.gotConn)
+	t.addDurationTag(span, "http.first_byte.duration_ms", t.wroteHeaders, t.gotFirstByte)
+	
+	// Add error information if present
+	if t.connectErr != nil {
+		span.SetTag("http.connect.error", t.connectErr.Error())
+	}
+	if t.tlsErr != nil {
+		span.SetTag("http.tls.error", t.tlsErr.Error())
+	}
+}
+
+// newClientTrace creates a ClientTrace that captures timing information
+func newClientTrace(timings *httpTraceTimings) *httptrace.ClientTrace {
+	return &httptrace.ClientTrace{
+		DNSStart:             func(httptrace.DNSStartInfo) { timings.dnsStart = time.Now() },
+		DNSDone:              func(httptrace.DNSDoneInfo) { timings.dnsEnd = time.Now() },
+		ConnectStart:         func(network, addr string) { timings.connectStart = time.Now() },
+		ConnectDone:          func(network, addr string, err error) { timings.connectEnd = time.Now(); timings.connectErr = err },
+		TLSHandshakeStart:    func() { timings.tlsStart = time.Now() },
+		TLSHandshakeDone:     func(_ tls.ConnectionState, err error) { timings.tlsEnd = time.Now(); timings.tlsErr = err },
+		GetConn:              func(hostPort string) { timings.getConnStart = time.Now() },
+		GotConn:              func(httptrace.GotConnInfo) { timings.gotConn = time.Now() },
+		WroteHeaders:         func() { timings.wroteHeaders = time.Now() },
+		GotFirstResponseByte: func() { timings.gotFirstByte = time.Now() },
+	}
+}
+
 // ObserveRoundTrip performs actions before the base [http.RoundTripper.RoundTrip] using the
 // provided [*config.RoundTripperConfig] (which cannot be nil). It returns the possibly modified
 // [*http.Request] and a function to be called after the base [http.RoundTripper.RoundTrip] function
@@ -45,7 +100,7 @@ func ObserveRoundTrip(cfg *config.RoundTripperConfig, req *http.Request) (*http.
 		tracer.SpanType(ext.SpanTypeHTTP),
 		tracer.ResourceName(resourceName),
 		tracer.Tag(ext.HTTPMethod, req.Method),
-		tracer.Tag(ext.HTTPURL, httptrace.URLFromRequest(req, cfg.QueryString)),
+		tracer.Tag(ext.HTTPURL, instrumentationhttptrace.URLFromRequest(req, cfg.QueryString)),
 		tracer.Tag(ext.Component, config.ComponentName),
 		tracer.Tag(ext.SpanKind, ext.SpanKindClient),
 		tracer.Tag(ext.NetworkDestinationName, url.Hostname()),
@@ -71,6 +126,13 @@ func ObserveRoundTrip(cfg *config.RoundTripperConfig, req *http.Request) (*http.
 		cfg.Before(req, span)
 	}
 
+	// Setup ClientTrace for detailed timing if enabled
+	var timings *httpTraceTimings
+	if cfg.ClientTimings {
+		timings = &httpTraceTimings{}
+		ctx = httptrace.WithClientTrace(ctx, newClientTrace(timings))
+	}
+
 	// Clone the request so we can modify it without causing visible side-effects to the caller...
 	req = req.Clone(ctx)
 	for k, v := range baggage.All(ctx) {
@@ -108,6 +170,10 @@ func ObserveRoundTrip(cfg *config.RoundTripperConfig, req *http.Request) (*http.
 			}
 		}
 
+		if cfg.ClientTimings && timings != nil {
+			timings.addTimingTags(span)
+		}
+
 		// Run the after hooks & finish the span
 		if cfg.After != nil {
 			cfg.After(resp, span)

contrib/net/http/option.go

@@ -191,6 +191,16 @@ func WithErrorCheck(fn func(err error) bool) RoundTripperOptionFn {
 	}
 }
 
+// WithClientTimings enables detailed HTTP request tracing using httptrace.ClientTrace.
+// When enabled, the integration will add timing information for DNS lookups,
+// connection establishment, TLS handshakes, and other HTTP request events as span tags.
+// This feature is disabled by default and adds minimal overhead when enabled.
+func WithClientTimings(enabled bool) RoundTripperOptionFn {
+	return func(cfg *internal.RoundTripperConfig) {
+		cfg.ClientTimings = enabled
+	}
+}
+
 func isClientError(statusCode int) bool {
 	return statusCode >= 400 && statusCode < 500
 }

contrib/net/http/roundtripper_test.go

@@ -581,6 +581,42 @@ func TestSpanOptions(t *testing.T) {
 	assert.Equal(t, tagValue, spans[0].Tag(tagKey))
 }
 
+func TestClientTimings(t *testing.T) {
+	assertClientTimings := func(t *testing.T, enabled bool, expectTags bool) {
+		mt := mocktracer.Start()
+		defer mt.Stop()
+
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			w.WriteHeader(http.StatusOK)
+		}))
+		defer srv.Close()
+
+		rt := WrapRoundTripper(http.DefaultTransport, WithClientTimings(enabled))
+		client := &http.Client{Transport: rt}
+		resp, err := client.Get(srv.URL)
+		assert.Nil(t, err)
+		defer resp.Body.Close()
+
+		spans := mt.FinishedSpans()
+		assert.Len(t, spans, 1)
+		span := spans[0]
+
+		hasTimingTags := span.Tag("http.connect.duration_ms") != nil ||
+			span.Tag("http.get_conn.duration_ms") != nil ||
+			span.Tag("http.first_byte.duration_ms") != nil
+
+		assert.Equal(t, expectTags, hasTimingTags)
+	}
+
+	t.Run("disabled", func(t *testing.T) {
+		assertClientTimings(t, false, false)
+	})
+
+	t.Run("enabled", func(t *testing.T) {
+		assertClientTimings(t, true, true)
+	})
+}
+
 func TestClientQueryStringCollected(t *testing.T) {
 	s := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
 		w.Write([]byte("Hello World"))