version: 1.10

package httptrace

import "net/http/httptrace"

Overview

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

Example:

  1. req, _ := http.NewRequest("GET", "http://example.com", nil)
  2. trace := &httptrace.ClientTrace{
  3.     GotConn: func(connInfo httptrace.GotConnInfo) {
  4.         fmt.Printf("Got Conn: %+v\n", connInfo)
  5.     },
  6.     DNSDone: func(dnsInfo httptrace.DNSDoneInfo) {
  7.         fmt.Printf("DNS Info: %+v\n", dnsInfo)
  8.     },
  9. }
  10. req = req.WithContext(httptrace.WithClientTrace(req.Context(), trace))
  11. _, err := http.DefaultTransport.RoundTrip(req)
  12. if err != nil {
  13.     log.Fatal(err)
  14. }

Index

Examples

Package files

trace.go

func WithClientTrace 

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

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.

type ClientTrace 

  1. type ClientTrace struct {
  2.     // GetConn is called before a connection is created or
  3.     // retrieved from an idle pool. The hostPort is the
  4.     // "host:port" of the target or proxy. GetConn is called even
  5.     // if there's already an idle cached connection available.
  6.     GetConn func(hostPort string)
  7.  
  8.     // GotConn is called after a successful connection is
  9.     // obtained. There is no hook for failure to obtain a
  10.     // connection; instead, use the error from
  11.     // Transport.RoundTrip.
  12.     GotConn func(GotConnInfo)
  13.  
  14.     // PutIdleConn is called when the connection is returned to
  15.     // the idle pool. If err is nil, the connection was
  16.     // successfully returned to the idle pool. If err is non-nil,
  17.     // it describes why not. PutIdleConn is not called if
  18.     // connection reuse is disabled via Transport.DisableKeepAlives.
  19.     // PutIdleConn is called before the caller's Response.Body.Close
  20.     // call returns.
  21.     // For HTTP/2, this hook is not currently used.
  22.     PutIdleConn func(err error)
  23.  
  24.     // GotFirstResponseByte is called when the first byte of the response
  25.     // headers is available.
  26.     GotFirstResponseByte func()
  27.  
  28.     // Got100Continue is called if the server replies with a "100
  29.     // Continue" response.
  30.     Got100Continue func()
  31.  
  32.     // DNSStart is called when a DNS lookup begins.
  33.     DNSStart func(DNSStartInfo)
  34.  
  35.     // DNSDone is called when a DNS lookup ends.
  36.     DNSDone func(DNSDoneInfo)
  37.  
  38.     // ConnectStart is called when a new connection's Dial begins.
  39.     // If net.Dialer.DualStack (IPv6 "Happy Eyeballs") support is
  40.     // enabled, this may be called multiple times.
  41.     ConnectStart func(network, addr string)
  42.  
  43.     // ConnectDone is called when a new connection's Dial
  44.     // completes. The provided err indicates whether the
  45.     // connection completedly successfully.
  46.     // If net.Dialer.DualStack ("Happy Eyeballs") support is
  47.     // enabled, this may be called multiple times.
  48.     ConnectDone func(network, addr string, err error)
  49.  
  50.     // TLSHandshakeStart is called when the TLS handshake is started. When
  51.     // connecting to a HTTPS site via a HTTP proxy, the handshake happens after
  52.     // the CONNECT request is processed by the proxy.
  53.     TLSHandshakeStart func()
  54.  
  55.     // TLSHandshakeDone is called after the TLS handshake with either the
  56.     // successful handshake's connection state, or a non-nil error on handshake
  57.     // failure.
  58.     TLSHandshakeDone func(tls.ConnectionState, error)
  59.  
  60.     // WroteHeaders is called after the Transport has written
  61.     // the request headers.
  62.     WroteHeaders func()
  63.  
  64.     // Wait100Continue is called if the Request specified
  65.     // "Expected: 100-continue" and the Transport has written the
  66.     // request headers but is waiting for "100 Continue" from the
  67.     // server before writing the request body.
  68.     Wait100Continue func()
  69.  
  70.     // WroteRequest is called with the result of writing the
  71.     // request and any body. It may be called multiple times
  72.     // in the case of retried requests.
  73.     WroteRequest func(WroteRequestInfo)
  74. }

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.

func ContextClientTrace 

  1. func ContextClientTrace(ctx context.Context) *ClientTrace

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

type DNSDoneInfo 

  1. type DNSDoneInfo struct {
  2.     // Addrs are the IPv4 and/or IPv6 addresses found in the DNS
  3.     // lookup. The contents of the slice should not be mutated.
  4.     Addrs []net.IPAddr
  5.  
  6.     // Err is any error that occurred during the DNS lookup.
  7.     Err error
  8.  
  9.     // Coalesced is whether the Addrs were shared with another
  10.     // caller who was doing the same DNS lookup concurrently.
  11.     Coalesced bool
  12. }

DNSDoneInfo contains information about the results of a DNS lookup.

type DNSStartInfo 

  1. type DNSStartInfo struct {
  2.     Host string
  3. }

DNSStartInfo contains information about a DNS request.

type GotConnInfo 

  1. type GotConnInfo struct {
  2.     // Conn is the connection that was obtained. It is owned by
  3.     // the http.Transport and should not be read, written or
  4.     // closed by users of ClientTrace.
  5.     Conn net.Conn
  6.  
  7.     // Reused is whether this connection has been previously
  8.     // used for another HTTP request.
  9.     Reused bool
  10.  
  11.     // WasIdle is whether this connection was obtained from an
  12.     // idle pool.
  13.     WasIdle bool
  14.  
  15.     // IdleTime reports how long the connection was previously
  16.     // idle, if WasIdle is true.
  17.     IdleTime time.Duration
  18. }

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

type WroteRequestInfo 

  1. type WroteRequestInfo struct {
  2.     // Err is any error encountered while writing the Request.
  3.     Err error
  4. }

WroteRequestInfo contains information provided to the WroteRequest hook.