Statsviz

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

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

Install

Get the latest version:

go get github.com/arl/statsviz@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

Examples

If you check any of the boxes below:

• you use some HTTP framework
• you want Statsviz to be located at /my/path/to/statsviz rather than /debug/statsviz
• you want Statsviz under https:// rather than http://
• you want Statsviz behind some middleware

Then you should call statsviz.NewServer() (with or without options depending on your use case) in order to access the Index() and Ws() methods.

srv, err := statsviz.NewServer(); // Create server or handle error
if err != nil { /* handle error */ }

// Do something with the handlers.
srv.Index()     // UI (dashboard) handler func
srv.Ws()        // Websocket handler func

Examples for the following cases, and more, are found in the _example directory:

• 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!

How Does That Work?

Statsviz is made of two parts:

• The Ws serves a Websocket endpoint. When a client connects, your program's runtime/metrics are sent to the browser, once per second, via the websocket connection.

• the Index http handler serves Statsviz user interface at /debug/statsviz at the address served by your program. When served, the UI connects to the Websocket endpoint and starts receiving data points.

Documentation

Go API

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

Web User Interface

Top Bar

Category Selector

Each plot belongs to one or more categories. The category selector allows you to filter the visible plots by categories.

Visible Time Range

Use the time range selector to define the visualized time span.

Show/Hide GC events

Show or hide the vertical lines representing garbage collection events.

Pause updates

Pause or resume the plot updates.

Plot Controls

Plots

Which plots are visible depends on:

• your Go version,since some plots are only available in newer versions.
• what plot categories are currently selected. By default all plots are shown.

Allocation and Free Rate

CGO Calls

CPU (GC)

CPU (Overall)

CPU (Scavenger)

Garbage Collection

GC Cycles

GC Pauses

GC Scan

GC Stack Size

Goroutines

Heap (Details)

Live Bytes

Live Objects

Memory Classes

MSpan/MCache

Mutex Wait

Runnable Time

Scheduling Events

Size Classes

GC Pauses

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.

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