zprof

README

zprof displays runtime profiling data over HTTP.

This is based on net/http/pprof; but has been rewritten quite a bit and is much nicer. You can display the callgraphs directly without downloading the file first, and a bunch of other changes. It doesn't give you the full power of the CLI, but overall it's fairly useful.

Import as zgo.at/zprof; you need Go 1.16.

Current status: fairly functional, still some things left to do. API may break.

Usage

Unlike net/http/pprof endpoints are not registered automatically; use zprof.NewHandler() to create a new handler to mount with your router, for example using net/http's default mux:

http.Handle("/profile*", zprof.NewHandler(zprof.Prefix("/profile")))

Or with chi:

r := chi.NewRouter()
r.Handle("/profile*", zprof.NewHandler(zprof.Prefix("/profile")))

Because you may not want to expose this to everyone you can add HTTP Basic auth with Auth():

http.Handle("/profile*", zprof.NewHandler(zprof.Prefix("/profile"),
    zprof.Auth("user", "passwd")))

Or handle auth in your regular app middleware.

You can use the zprof.Profile() shortcut if your application doesn't have a HTTP server:

zprof.Profile("")

This will set up a HTTP server on localhost:6060; use the first parameter to configure the address.

Like with net/http/pprof, you can still use the commandline tool if you prefer:

$ go tool pprof http://localhost:6060/debug/pprof/heap

$ wget -O trace.out http://localhost:6060/debug/pprof/trace?seconds=5
$ go tool trace trace.out

Documentation

Overview

Package zprof serves runtime profiling data.

Index

• Constants
• Variables
• func Profile(addr string, opts ...HandlerOpt)
• type Handler
  • func NewHandler(opts ...HandlerOpt) Handler
  • func (h Handler) Index(w http.ResponseWriter, r *http.Request) error
  • func (h Handler) PProf(name string) func(w http.ResponseWriter, r *http.Request) error
  • func (h Handler) Profile(w http.ResponseWriter, r *http.Request) error
  • func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (h Handler) SetProfileRates(w http.ResponseWriter, r *http.Request) error
  • func (h Handler) Symbol(w http.ResponseWriter, r *http.Request) error
  • func (h Handler) Trace(w http.ResponseWriter, r *http.Request) error
• type HandlerOpt

Constants

const (
	ReportBinary = "bin"
	ReportDebug  = "dbg"
	ReportDebug2 = "dbg2"
	ReportTop    = "top"
	ReportTraces = "traces"
	ReportSVG    = "svg"
)

Variables

var (
	// Prefix sets the prefix to the path you serve the profiles on, for example
	// "/profile".
	Prefix = func(prefix string) HandlerOpt {
		return func(h *Handler) { h.prefix = strings.TrimRight(prefix, "/") }
	}

	// Auth adds HTTP Basic auth.
	Auth = func(user, passwd string) HandlerOpt {
		return func(h *Handler) { h.user, h.passwd = []byte(user), []byte(passwd) }
	}

	// HTTPS enforces using https:// links; this can't always be reliably
	// detected.
	HTTPS = func(https bool) HandlerOpt {
		return func(h *Handler) { h.https = https }
	}
)

var BlockRate *int64 = func() *int64 {
	var z int64
	return &z
}()

BlockRate remembers the current block profile rate.

There is no way to query the block profile rate; so keep track of it here. If you call SetBlockProfileRate() in your program then you may want to set this value as well to ensure the UI is displayed correct.

Use atomic.StoreInt64() and atomic.LoadInt64() to set and get the value.

Functions

func Profile

func Profile(addr string, opts ...HandlerOpt)

Profile starts a new HTTP server on addr to profile this application.

Errors are considered non-fatal, but will be printed to stderr. "localhost:6060" will be used if addr is an empty string.

The auth can be used to set up HTTP Basic auth; the format is as "user:password". No auth is added if this is an empty string.

Types

type Handler

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

func NewHandler

func NewHandler(opts ...HandlerOpt) Handler

NewHandler creates a new Handler instance.

func (Handler) Index

func (h Handler) Index(w http.ResponseWriter, r *http.Request) error

Index serves an overview of all profiles and metrics.

func (Handler) PProf

func (h Handler) PProf(name string) func(w http.ResponseWriter, r *http.Request) error

PProf serves pprof profiles based on the name.

Available profiles: goroutine, threadcreate, heap, allocs, block, mutex

func (Handler) Profile

func (h Handler) Profile(w http.ResponseWriter, r *http.Request) error

Profile creates a pprof formatted CPU profile.

Profiling lasts for duration specified in seconds GET parameter, or for 30 seconds if not specified.

func (Handler) ServeHTTP

func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (Handler) SetProfileRates

func (h Handler) SetProfileRates(w http.ResponseWriter, r *http.Request) error

SetProfileRates sets the block and mutex profile rates.

func (Handler) Symbol

func (h Handler) Symbol(w http.ResponseWriter, r *http.Request) error

Symbol looks up the program counters listed in the request, responding with a table mapping program counters to function names.

func (Handler) Trace

func (h Handler) Trace(w http.ResponseWriter, r *http.Request) error

Trace shows the execution trace in binary form.

Tracing lasts for duration specified in seconds GET parameter, or for 1 second if not specified.

type HandlerOpt

type HandlerOpt func(*Handler)