golang.org/toolchain@v0.0.1-go1.9rc2.windows-amd64/blog/content/http-tracing.article (about)

     1  Introducing HTTP Tracing
     2  4 Oct 2016
     3  Tags: http, technical
     4  
     5  Jaana Burcu Dogan
     6  
     7  * Introduction
     8  
     9  In Go 1.7 we introduced HTTP tracing, a facility to gather fine-grained
    10  information throughout the lifecycle of an HTTP client request.
    11  Support for HTTP tracing is provided by the [[https://golang.org/pkg/net/http/httptrace/][`net/http/httptrace`]]
    12  package. The collected information can be used for debugging latency issues,
    13  service monitoring, writing adaptive systems, and more.
    14  
    15  * HTTP events
    16  
    17  The `httptrace` package provides a number of hooks to gather information
    18  during an HTTP round trip about a variety of events. These events include:
    19  
    20  - Connection creation
    21  - Connection reuse
    22  - DNS lookups
    23  - Writing the request to the wire
    24  - Reading the response
    25  
    26  * Tracing events
    27  
    28  You can enable HTTP tracing by putting an
    29  [[https://golang.org/pkg/net/http/httptrace/#ClientTrace][`*httptrace.ClientTrace`]]
    30  containing hook functions into a request's [[https://golang.org/pkg/context/#Context][`context.Context`]].
    31  Various [[https://golang.org/pkg/net/http/#RoundTripper][`http.RoundTripper`]]
    32  implementations report the internal events by
    33  looking for context's `*httptrace.ClientTrace` and calling the relevant hook functions.
    34  
    35  The tracing is scoped to the request's context and users should
    36  put a `*httptrace.ClientTrace` to the request context before they start a request.
    37  
    38  .code http-tracing/trace.go /START/,/END/
    39  
    40  During a round trip, `http.DefaultTransport` will invoke each hook
    41  as an event happens. The program above will print the DNS
    42  information as soon as the DNS lookup is complete. It will similarly print
    43  connection information when a connection is established to the request's host.
    44  
    45  * Tracing with http.Client
    46  
    47  The tracing mechanism is designed to trace the events in the lifecycle
    48  of a single `http.Transport.RoundTrip`. However, a client may
    49  make multiple round trips to complete an HTTP request. For example, in the case
    50  of a URL redirection, the registered hooks will be called as many times as the
    51  client follows HTTP redirects, making multiple requests.
    52  Users are responsible for recognizing such events at the `http.Client` level.
    53  The program below identifies the current request by using an
    54  `http.RoundTripper` wrapper.
    55  
    56  .code http-tracing/client.go
    57  
    58  The program will follow the redirect of google.com to www.google.com and will output:
    59  
    60      Connection reused for https://google.com? false
    61      Connection reused for https://www.google.com/? false
    62  
    63  The Transport in the `net/http` package supports tracing of both HTTP/1
    64  and HTTP/2 requests.
    65  
    66  If you are an author of a custom `http.RoundTripper` implementation,
    67  you can support tracing by checking the request context for an
    68  `*httptest.ClientTrace` and invoking the relevant hooks as the events occur.
    69  
    70  * Conclusion
    71  
    72  HTTP tracing is a valuable addition to Go for those who are interested
    73  in debugging HTTP request latency and writing tools for network debugging
    74  for outbound traffic.
    75  By enabling this new facility, we hope to see HTTP debugging, benchmarking
    76  and visualization tools from the community — such as
    77  [[https://github.com/davecheney/httpstat][httpstat]].