golanglib / statsviz

:rocket: Visualise Go program runtime metrics in real time in your browser

Statsviz

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

---

Special thanks to my sponsors:

Foresight: Increase CI/CD Health & Test Performance

Foresight provides full visibility and deep insights into the health and performance of your tests and CI pipelines. Assess the risk of code changes, deal with flaky tests, see workflow and test trends over time, and improve the contributing experience with Foresight.

---

• Usage
• How does that work?
• Documentation
  • Go API
  • User interface
    • Plots
• Examples
• Questions / Troubleshooting
• Contributing
• Changelog
• License

Usage

Download the latest version:

go get github.com/arl/statsviz@latest

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 section for questions.
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

See MIT License