package httptrace

Import Path
	net/http/httptrace (on go.dev)

Dependency Relation
	imports 7 packages, and imported by one package


Involved Source Files

	
		Package httptrace provides mechanisms to trace the events within
		HTTP client requests.


Code Examples

	
		package main
		
		import (
			"fmt"
			"log"
			"net/http"
			"net/http/httptrace"
		)
		
		func main() {
			req, _ := http.NewRequest("GET", "http://example.com", nil)
			trace := &httptrace.ClientTrace{
				GotConn: func(connInfo httptrace.GotConnInfo) {
					fmt.Printf("Got Conn: %+v\n", connInfo)
				},
				DNSDone: func(dnsInfo httptrace.DNSDoneInfo) {
					fmt.Printf("DNS Info: %+v\n", dnsInfo)
				},
			}
			req = req.WithContext(httptrace.WithClientTrace(req.Context(), trace))
			_, err := http.DefaultTransport.RoundTrip(req)
			if err != nil {
				log.Fatal(err)
			}
		}




Package-Level Type Names (total 6, in which 5 are exported)


	/* sort exporteds by:  |  */
	
		ClientTrace is a set of hooks to run at various stages of an outgoing
		HTTP request. Any particular hook may be nil. Functions may be
		called concurrently from different goroutines and some may be called
		after the request has completed or failed.
		
		ClientTrace currently traces a single HTTP request & response
		during a single round trip and has no hooks that span a series
		of redirected requests.
		
		See https://blog.golang.org/http-tracing for more.

		
			
				ConnectDone is called when a new connection's Dial
				completes. The provided err indicates whether the
				connection completed successfully.
				If net.Dialer.DualStack ("Happy Eyeballs") support is
				enabled, this may be called multiple times.

			
				ConnectStart is called when a new connection's Dial begins.
				If net.Dialer.DualStack (IPv6 "Happy Eyeballs") support is
				enabled, this may be called multiple times.

			
				DNSDone is called when a DNS lookup ends.

			
				DNSStart is called when a DNS lookup begins.

			
				GetConn is called before a connection is created or
				retrieved from an idle pool. The hostPort is the
				"host:port" of the target or proxy. GetConn is called even
				if there's already an idle cached connection available.

			
				Got100Continue is called if the server replies with a "100
				Continue" response.

			
				Got1xxResponse is called for each 1xx informational response header
				returned before the final non-1xx response. Got1xxResponse is called
				for "100 Continue" responses, even if Got100Continue is also defined.
				If it returns an error, the client request is aborted with that error value.

			
				GotConn is called after a successful connection is
				obtained. There is no hook for failure to obtain a
				connection; instead, use the error from
				Transport.RoundTrip.

			
				GotFirstResponseByte is called when the first byte of the response
				headers is available.

			
				PutIdleConn is called when the connection is returned to
				the idle pool. If err is nil, the connection was
				successfully returned to the idle pool. If err is non-nil,
				it describes why not. PutIdleConn is not called if
				connection reuse is disabled via Transport.DisableKeepAlives.
				PutIdleConn is called before the caller's Response.Body.Close
				call returns.
				For HTTP/2, this hook is not currently used.

			
				TLSHandshakeDone is called after the TLS handshake with either the
				successful handshake's connection state, or a non-nil error on handshake
				failure.

			
				TLSHandshakeStart is called when the TLS handshake is started. When
				connecting to an HTTPS site via an HTTP proxy, the handshake happens
				after the CONNECT request is processed by the proxy.

			
				Wait100Continue is called if the Request specified
				"Expect: 100-continue" and the Transport has written the
				request headers but is waiting for "100 Continue" from the
				server before writing the request body.

			
				WroteHeaderField is called after the Transport has written
				each request header. At the time of this call the values
				might be buffered and not yet written to the network.

			
				WroteHeaders is called after the Transport has written
				all request headers.

			
				WroteRequest is called with the result of writing the
				request and any body. It may be called multiple times
				in the case of retried requests.

		
			
		
			func ContextClientTrace(ctx context.Context) *ClientTrace
		
			func WithClientTrace(ctx context.Context, trace *ClientTrace) context.Context
			


	
		DNSDoneInfo contains information about the results of a DNS lookup.

		
			
				Addrs are the IPv4 and/or IPv6 addresses found in the DNS
				lookup. The contents of the slice should not be mutated.

			
				Coalesced is whether the Addrs were shared with another
				caller who was doing the same DNS lookup concurrently.

			
				Err is any error that occurred during the DNS lookup.



	
		DNSStartInfo contains information about a DNS request.

		
			Host string


	
		GotConnInfo is the argument to the ClientTrace.GotConn function and
		contains information about the obtained connection.

		
			
				Conn is the connection that was obtained. It is owned by
				the http.Transport and should not be read, written or
				closed by users of ClientTrace.

			
				IdleTime reports how long the connection was previously
				idle, if WasIdle is true.

			
				Reused is whether this connection has been previously
				used for another HTTP request.

			
				WasIdle is whether this connection was obtained from an
				idle pool.



	
		WroteRequestInfo contains information provided to the WroteRequest
		hook.

		
			Err error


	


Package-Level Functions (total 2, both are exported)


	
		ContextClientTrace returns the ClientTrace associated with the
		provided context. If none, it returns nil.


	
		WithClientTrace returns a new context based on the provided parent
		ctx. HTTP client requests made with the returned context will use
		the provided trace hooks, in addition to any previous hooks
		registered with ctx. Any hooks defined in the provided trace will
		be called first.