statsviz

README

Statsviz

Instant live visualization of your Go application runtime statistics (GC, MemStats, etc.).

• Import "github.com/arl/statsviz"
• Register statsviz HTTP handlers
• Start your program
• Open your browser at http://host:port/debug/statsviz
• Enjoy...

How does that work?

Statsviz serves 2 HTTP handlers.

The first one (by default /debug/statsviz) serves an html/js user interface showing some initially empty plots.

When you points your browser to statsviz user interface page, it connects to statsviz second HTTP handler. This second handler then upgrades the connection to the websocket protocol and starts a goroutine that periodically calls runtime.ReadMemStats, sending the result to the user interface, which inturn, updates the plots.

Stats are stored in-browser inside a circular buffer which keep tracks of a predefined number of datapoints, 60, so one minute-worth of data, by default. You can change the frequency at which stats are sent by passing SendFrequency to Register.

Usage

go get github.com/arl/statsviz

Either Register statsviz HTTP handlers with the http.ServeMux you're using (preferred method):

mux := http.NewServeMux()
statsviz.Register(mux)

Or register them with the http.DefaultServeMux:

statsviz.RegisterDefault()

If your application is not already running an HTTP server, you need to start one. Add "net/http" and "log" to your imports and the following code to your main function:

go func() {
    log.Println(http.ListenAndServe("localhost:6060", nil))
}()

By default the handled path is /debug/statsviz/.

Then open your browser at http://localhost:6060/debug/statsviz/

Plots

On the plots where it matters, garbage collections are shown as vertical lines.

Heap

MSpans / MCaches

Size classes heatmap

Objects

Goroutines

GC/CPU fraction

Examples

Have a look at the _example directory to see some different ways to register Statsviz HTTP handlers, such as:

• using http.DefaultServeMux
• using your own http.ServeMux
• register at /foo/bar instead of /debug/statviz
• use https:// rather than http://
• using with various Go HTTP libraries/frameworks:
  • fasthttp
  • gin
  • and many others thanks to wonderful contributors!

Contributing

Pull-requests are welcome! More details in CONTRIBUTING.md

Roadmap

• add stop-the-world duration heatmap
• increase data retention
• light/dark mode selector
• plot image export as png
• save timeseries to disk
• load from disk previously saved timeseries

Changelog

See CHANGELOG.md.

License

• MIT License

Documentation

Overview

Package statsviz serves via its HTTP server an HTML page displaying live visualization of the application runtime statistics.

Either Register statsviz HTTP handlers with the http.ServeMux you're using (preferred method):

mux := http.NewServeMux()
statsviz.Register(mux)

Or register them with the http.DefaultServeMux:

statsviz.RegisterDefault()

If your application is not already running an HTTP server, you need to start one. Add "net/http" and "log" to your imports and the following code to your main function:

go func() {
	log.Println(http.ListenAndServe("localhost:6060", nil))
}()

Index

• Variables
• func IndexAtRoot(root string) http.HandlerFunc
• func NewWsHandler(frequency time.Duration) http.HandlerFunc
• func Register(mux *http.ServeMux, opts ...OptionFunc) error
• func RegisterDefault(opts ...OptionFunc) error
• type OptionFunc
  • func Root(root string) OptionFunc
  • func SendFrequency(freq time.Duration) OptionFunc

Variables

var Index = IndexAtRoot(defaultRoot)

Index responds to a request for /debug/statsviz with the statsviz HTML page which shows a live visualization of the statistics sent by the application over the websocket handler Ws.

var Ws = NewWsHandler(defaultSendFrequency)

Ws is a default Websocket handler, created with NewWsHandler, sending statistics at the default frequency of 1 message per second.

Functions

func IndexAtRoot

func IndexAtRoot(root string) http.HandlerFunc

IndexAtRoot returns an index statsviz handler rooted at root. It's useful if you desire your server to responds with the statsviz HTML page at a path that is different than /debug/statsviz.

func NewWsHandler

func NewWsHandler(frequency time.Duration) http.HandlerFunc

NewWsHandler returns a handler that upgrades the HTTP server connection to the WebSocket protocol and sends application statistics at the given frequency.

If the upgrade fails, an HTTP error response is sent to the client.

func Register

func Register(mux *http.ServeMux, opts ...OptionFunc) error

Register registers statsviz HTTP handlers on the provided mux.

func RegisterDefault

func RegisterDefault(opts ...OptionFunc) error

RegisterDefault registers statsviz HTTP handlers on the default serve mux.

Note this is not advised on a production server, unless it only serves on localhost.

Types

type OptionFunc

type OptionFunc func(s *server) error

An OptionFunc is a server configuration option.

func Root

func Root(root string) OptionFunc

Root sets the root path of statsviz handlers.

func SendFrequency

func SendFrequency(freq time.Duration) OptionFunc

SendFrequency defines the frequency at which statistics are sent from the application to the HTML page.