Awesome Open Source
Awesome Open Source

Statsviz

go.dev reference Mentioned in Awesome Go Latest tag

Test Actions Status Test Actions Status codecov

Statsviz Gopher Logo statsviz ui


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:

menu
  • 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:

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

Plots

Heap (global)
Heap (global) image
Heap (details)
Heap (details) image
Live Objects in Heap
Live Objects in Heap image
Live Bytes in Heap
Live Bytes in Heap image
MSpan/MCache
MSpan/MCache image
Goroutines
Goroutines image
Size Classes
Size Classes image
Stop-the-world Pause Latencies
Stop-the-world Pause Latencies image
Time Goroutines Spend in 'Runnable'
Time Goroutines Spend in 'Runnable' image
Starting Size of Goroutines Stacks
Time Goroutines Spend in 'Runnable' image
Goroutine Scheduling Events
Time Goroutines Spend in 'Runnable' image
CGO Calls
CGO Calls image

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

Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Golang (163,926
Http (30,198
Visualization (15,423
Metrics (13,659
Monitoring (11,868
Live (11,448
Plot (9,991
Golang Library (1,673
Gin (1,670
Gorilla (622
Garbage Collector (319