Statsviz

Visualize real time plots of your Go program runtime metrics, including heap, objects, goroutines, GC pauses, scheduler and more, in your browser.

• Statsviz
  • Install
  • Usage
  • Advanced Usage
  • How Does That Work?
  • Documentation
    • Go API
    • User interface
    • Plots
    • User Plots
  • Examples
  • Questions / Troubleshooting
  • Contributing
  • Changelog
  • License: MIT

Install

Download the latest version:

go get github.com/arl/statsviz@latest

Please note that, as new metrics are added to the /runtime/metrics package, new plots are added to Statsviz. This also means that the presence of some plots on the dashboard depends on the Go version you're using.

When in doubt, use the latest ;-)

Usage

Register Statsviz HTTP handlers with your application http.ServeMux.

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

go func() {
    log.Println(http.ListenAndServe("localhost:8080", mux))
}()

Open your browser at http://localhost:8080/debug/statsviz

Advanced Usage

If you want more control over Statsviz HTTP handlers, examples are:

• you're using some HTTP framework
• you want to place Statsviz handler behind some middleware

then use statsviz.NewServer to obtain a Server instance. Both the Index() and Ws() methods return http.HandlerFunc.

srv, err := statsviz.NewServer(); // Create server or handle error
srv.Index()                       // UI (dashboard) http.HandlerFunc
srv.Ws()                          // Websocket http.HandlerFunc

Please look at examples of usage in the Examples directory.

How Does That Work?

statsviz.Register registers 2 HTTP handlers within the given http.ServeMux:

• the Index handler serves Statsviz user interface at /debug/statsviz at the address served by your program.

• The Ws serves a Websocket endpoint. When the browser connects to that endpoint, runtime/metrics are sent to the browser, once per second.

Data points are in a browser-side circular-buffer.

Documentation

Go API

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

User interface

Controls at the top of the page act on all plots:

• the groom shows/hides the vertical lines representing garbage collections.
• the time range selector defines the visualized time span.
• the play/pause icons stops and resume the refresh of the plots.
• the light/dark selector switches between light and dark modes.

On top of each plot there are 2 icons:

• the camera downloads a PNG image of the plot.
• the info icon shows details about the metrics displayed.

Plots

Depending on your go version, some plots may not be available.

Heap (global)

Heap (details)

Live Objects in Heap

Live Bytes in Heap

MSpan/MCache

Memory classes

Goroutines

Size Classes

GC Scan

GC Cycles

Stop-the-world Pause Latencies

CPU Classes (GC)

Time Goroutines Spend in 'Runnable' state

Time Goroutines Spend Blocked on Mutexes

Starting Size of Goroutines Stacks

Goroutine Scheduling Events

CGO Calls

User Plots

Since v0.6 you can add your own plots to Statsviz dashboard, in order to easily visualize your application metrics next to runtime metrics.

Please see the userplots example.

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/statsviz
• use https:// rather than http://
• register Statsviz handlers with various Go HTTP libraries/frameworks:
  • echo
  • fasthttp
  • fiber
  • gin
  • and many others thanks to many contributors!

Questions / Troubleshooting

Either use GitHub's discussions or come to say hi and ask a live question on #statsviz channel on Gopher's slack.

Contributing

Please use issues for bugs and feature requests.
Pull-requests are always welcome!
More details in CONTRIBUTING.md.

Changelog

See CHANGELOG.md.

License: MIT

See LICENSE