Key Takeaways

• Granular Visibility: httptrace allows developers to hook into specific stages of the HTTP lifecycle, including DNS lookup, connection establishment, and TLS handshakes.
• Latency Bottleneck Identification: Use it to distinguish between network-level delays (DNS/TCP) and application-level delays (TTFB).
• Connection Pool Optimization: Essential for debugging whether your application is reusing connections or constantly creating new ones.
• Zero Overhead: When not actively instrumented, the impact on production performance is negligible.

In high-performance microservices architecture, "slow" is often a vague symptom. Is the delay caused by a slow DNS provider? A heavy TLS handshake? Or is the remote server simply taking too long to process the request? Standard HTTP logging tells you that a request was slow, but httptrace tells you why.

The net/http/httptrace package in Go provides a powerful mechanism to instrument the internal mechanics of an HTTP client request. This playbook provides a systematic approach to implementing tracing to optimize your network stack.

The HTTP Lifecycle: Understanding the Hooks

To use httptrace effectively, you must understand the sequence of events it monitors. The package provides a ClientTrace struct that accepts function callbacks for various stages.

1. DNS and Connection Phase

Before a single byte of HTTP data is sent, the network stack must resolve the hostname and establish a socket. Hooks include:

• DNSStart / DNSDone: Measures the time taken to resolve a domain name.
• ConnectStart / ConnectDone: Measures the TCP handshake duration.

2. The TLS Handshake Phase

For HTTPS requests, the security negotiation is often the most expensive part of the connection setup. Hooks include:

• TLSHandshakeStart / TLSHandshakeDone: Critical for identifying overhead caused by certificate validation or cipher negotiation.

3. Request and Response Phase

Once the pipe is open, the actual data transfer begins. Hooks include:

• WroteRequest: Indicates when the request has been fully sent to the wire.
• GotFirstResponseByte: The holy grail of latency metrics—measures the Time to First Byte (TTFB).

Implementation Playbook: Step-by-Step

Follow this workflow to integrate httptrace into your diagnostic toolset.

Step 1: Define your Trace Struct

Create a custom struct to capture the timestamps of each event. Using time.Time allows you to calculate precise durations later.

Step 2: Attach the Trace to the Request

You do not wrap the http.Client; instead, you wrap the http.Request using req.WithContext.

Step 3: The Implementation Pattern

Use the following logic pattern in your Go code:

1. Initialize a httptrace.ClientTrace with your timing callbacks.
2. Create a new context using httptrace.WithClientTrace(ctx, trace).
3. Pass this context into your http.NewRequestWithContext call.
4. Execute the request and calculate the deltas between your captured timestamps.

Comparison: When to Use Which Tool

Performance Debugging Checklist

Use this checklist when investigating latency spikes in your Go-based services:

• Check DNS Latency: