whathappens

README

whathappens

A library and CLI for monitoring what happens during an HTTP transaction.

whathappens is a wrapper around the httptrace Golang package. It can be used to instrument health checks, profile network performance and measure SLIs of a service from a client's perspective.

Phases

|------------------- Request Duration ---------------------------|
|------------------- Time-to-First-Byte -----------------|
  BLOCKED  DNS             CONNECT             SEND  WAIT RECEIVE
+---------+---+------------------------------+------+----+-------+
|         |   |                              |      |    |       |
|         |   |    +-------------------------+      |    |       |
|         |   |    |   SSL/TLS NEGOTIATION   |      |    |       |
+---------+---+----+-------------------------+------+----+-------+

• Blocked - Time spent queued for client network resources.
• DNS - Time spent resolving a DNS address to an IP.
• Connect - Time spent establishing a connection to the server.
• SSL - Time spent during the TLS handshake, if the request used SSL/TLS. If included, SSL timings are also included in Connect timings.
• Send - Time spent sending the request.
• Wait - Time spent waiting for the server to respond.
• Receive - Time spent reading the response from the server.

The model aligns with the HTTP Archive (HAR) 1.2 specification for recording tracing metrics.

Documentation

Overview

Package whathappens provides HTTP request tracing frameworks for instrumenting health checks and performance profiling.

Example

package main

import (
	"fmt"
	"log"
	"net/http"
	"net/http/httptrace"

	"go.uber.org/zap"
)

func init() {
	// Reduce log verbosity
	Config.SetLevel(zap.WarnLevel)
}

func main() {
	req, _ := http.NewRequest("GET", "http://1.1.1.1/", nil)

	// Make a RoundTripper to track the request
	t := NewTransport()

	// Create an HTTP client that uses the transport
	client, _ := t.Client()

	// Set the request to use a tracer and the transport
	req = req.WithContext(
		httptrace.WithClientTrace(req.Context(), t.ClientTrace()),
	)

	// Use the tracer client to make the request. While performing the request,
	// lifecycle hooks will be triggered and timings will be logged
	res, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}

	// The client will have been redirected to the HTTPS site
	fmt.Println(res.Request.URL)
}

Output:

https://1.1.1.1/

Index

• Variables
• func ElapsedSince(start time.Time) float32
• type ConfigProperties
  • func DefaultConfig() *ConfigProperties
  • func (c *ConfigProperties) Logger() *zap.Logger
  • func (c *ConfigProperties) SetLevel(level zapcore.Level)
  • func (c *ConfigProperties) SyncLogger()
  • func (c *ConfigProperties) Timeout() time.Duration
• type Timings
• type Trace
  • func (t *Trace) Timings() ([]*Timings, error)
• type Transport
  • func NewTransport() (t *Transport)
  • func (t *Transport) Client() (*http.Client, error)
  • func (t *Transport) ClientTrace() *httptrace.ClientTrace
  • func (t *Transport) ConnectDone(network, addr string, err error)
  • func (t *Transport) ConnectStart(network, addr string)
  • func (t *Transport) DNSDone(info httptrace.DNSDoneInfo)
  • func (t *Transport) DNSStart(info httptrace.DNSStartInfo)
  • func (t *Transport) GetConn(hostport string)
  • func (t *Transport) Got1xxResponse(code int, _ textproto.MIMEHeader) error
  • func (t *Transport) GotConn(info httptrace.GotConnInfo)
  • func (t *Transport) GotFirstResponseByte()
  • func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)
  • func (t *Transport) TLSHandshakeDone(state tls.ConnectionState, err error)
  • func (t *Transport) TLSHandshakeStart()
  • func (t *Transport) Timings() ([]*Timings, error)
• type TransportLog

Examples

• Package

Variables

var ErrNilTransport = errors.New("nil transport")

ErrNilTransport is returned when a nil Transport is referenced.

var ErrNotImplemented = errors.New("not yet implemented")

ErrNotImplemented is an error returned when planned functionality is not yet implemented.

var (
	// Sink is the package-wide metrics sink.
	Sink *metrics.Metrics
)

Functions

func ElapsedSince

func ElapsedSince(start time.Time) float32

ElapsedSince returns the time since a start time in a floating-point number of milliseconds.

Types

type ConfigProperties

type ConfigProperties struct {
	// contains filtered or unexported fields
}

var Config *ConfigProperties

func DefaultConfig

func DefaultConfig() *ConfigProperties

DefaultConfig creates a new default config

func (*ConfigProperties) Logger

func (c *ConfigProperties) Logger() *zap.Logger

Logger returns the configured global logger.

func (*ConfigProperties) SetLevel

func (c *ConfigProperties) SetLevel(level zapcore.Level)

func (*ConfigProperties) SyncLogger

func (c *ConfigProperties) SyncLogger()

SyncLogger syncs the underlying logger.

func (*ConfigProperties) Timeout

func (c *ConfigProperties) Timeout() time.Duration

type Timings

type Timings struct {
	Blocked float32 `json:"blocked"`
	DNS     float32 `json:"dns"`
	Connect float32 `json:"connect"`
	Send    float32 `json:"send"`
	Wait    float32 `json:"wait"`
	Receive float32 `json:"receive"`
	SSL     float32 `json:"ssl"`
	Comment string  `json:"comment"`
}

Timings is a HTTP Archive (HAR) 1.2 compatible object describing time elapsed during various phases of a request-response round trip. All times are specified in milliseconds.

Per the HAR spec:

- The Send, Wait and Receive timings are required and must have non-negative values. - Use -1 for timing values that do not apply the request.

See http://www.softwareishard.com/blog/har-12-spec/#timings for more.

type Trace

type Trace struct {
	ID string
	// contains filtered or unexported fields
}

Trace is a context used for tracking a full round trip of a request, inclusive of redirects.

func (*Trace) Timings

func (t *Trace) Timings() ([]*Timings, error)

Timings returns the timings observed during a Trace.

type Transport

type Transport struct {
	// contains filtered or unexported fields
}

Transport is an http.RoundTripper that keeps track of the in-flight request and implements hooks to report HTTP tracing events. A Transport should only be used once per HTTP transaction but reused if following redirects.

A Transport's ID and the IDs of requests made using it are RFC 4122 UUIDs.

FIXME: Transports following redirects destroy previous request data.

func NewTransport

func NewTransport() (t *Transport)

NewTransport allocates a transport and assigns it a UUID.

func (*Transport) Client

func (t *Transport) Client() (*http.Client, error)

Client returns an http.Client that will use the transport.

func (*Transport) ClientTrace

func (t *Transport) ClientTrace() *httptrace.ClientTrace

ClientTrace returns an httptrace.ClientTrace that performs the given timings when its hooks are triggered.

func (*Transport) ConnectDone

func (t *Transport) ConnectDone(network, addr string, err error)

func (*Transport) ConnectStart

func (t *Transport) ConnectStart(network, addr string)

func (*Transport) DNSDone

func (t *Transport) DNSDone(info httptrace.DNSDoneInfo)

func (*Transport) DNSStart

func (t *Transport) DNSStart(info httptrace.DNSStartInfo)

func (*Transport) GetConn

func (t *Transport) GetConn(hostport string)

func (*Transport) Got1xxResponse

func (t *Transport) Got1xxResponse(code int, _ textproto.MIMEHeader) error

func (*Transport) GotConn

func (t *Transport) GotConn(info httptrace.GotConnInfo)

func (*Transport) GotFirstResponseByte

func (t *Transport) GotFirstResponseByte()

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper and wraps http.DefaultTransport.RoundTrip to keep track of the current request.

func (*Transport) TLSHandshakeDone

func (t *Transport) TLSHandshakeDone(state tls.ConnectionState, err error)

func (*Transport) TLSHandshakeStart

func (t *Transport) TLSHandshakeStart()

func (*Transport) Timings

func (t *Transport) Timings() ([]*Timings, error)

Timings returns the timings observed by the Transport as a slice of Timings.

type TransportLog

type TransportLog struct {
	Time      time.Time
	Transport string
	Request   string
	Hook      string
}