Statsviz

Visualise Go program runtime metrics data in real time: heap, objects, goroutines, GC pauses, scheduler, etc. in your browser.

Usage

Download the latest version:

go get github.com/arl/[email protected]

Register statsviz endpoint on your server http.ServeMux (preferred method):

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

Or register on http.DefaultServeMux:

statsviz.RegisterDefault()

By default statsviz is served at /debug/statsviz/.

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))
}()

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

How does that work?

Statsviz serves 2 HTTP endpoints:

• The first one (/debug/statsviz) serves a web page with statsviz user interface, showing initially empty plots.

• The second HTTP handler (/debug/statsviz/ws) listens for a WebSocket connection that will be initiated by statsviz web page as soon as it's loaded in your browser.

That's it, now your application sends all runtime/metrics data points to the web page, once per second.

Data points are stored in-browser in a circular buffer which keep tracks of a predefined number of datapoints.

Documentation

Go API

Check out the API reference on pkg.go.dev.

User interface

The controls at the top of the page act on all plots:

• the groom icon shows/hides the vertical lines representing garbage collections.
• the time range selector defines the visualized time span.
• the play/pause icon allows to stop plots from being refreshed.

On top of each plot you'll find 2 icons:

• the camera icon downloads the plot as a PNG image.
• the info icon shows information about the current plot.

Plots

Heap (global)

Heap (details)

Live Objects in Heap

Live Bytes in Heap

MSpan/MCache

Goroutines

Size Classes

Stop-the-world Pause Latencies

Time Goroutines Spend in 'Runnable'

Starting Size of Goroutines Stacks

Goroutine Scheduling Events

CGO Calls

Examples

Check out the _example directory to see various ways to use Statsviz, such as:

• use of http.DefaultServeMux or your own http.ServeMux
• wrap HTTP handler behind a middleware
• register the web page at /foo/bar instead of /debug/statviz
• use https:// rather than http://
• register statsviz handlers with various Go HTTP libraries/frameworks:
  • fasthttp
  • gin
  • and many others thanks to many awesome contributors!

Questions / Troubleshooting

Use the discussions sections for questions.
Please use issues for bugs and feature requests.

Contributing

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

Changelog

See CHANGELOG.md.

License

See MIT License