statsviz

README

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

Documentation

Overview

Package statsviz allows to visualise Go program runtime metrics data in real time: heap, objects, goroutines, GC pauses, scheduler, etc. in your browser.

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/.

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.