statsviz

README

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

Documentation

Overview

Package statsviz allows visualizing Go runtime metrics data in real time in your browser.

Register a Statsviz HTTP handlers with your server's http.ServeMux (preferred method):

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

Alternatively, you can register with http.DefaultServeMux:

ss := statsviz.Server{}
s.Register(http.DefaultServeMux)

By default, Statsviz is served at http://host:port/debug/statsviz/. This, and other settings, can be changed by passing some Option to NewServer.

If your application is not already running an HTTP server, you need to start one. Add "net/http" and "log" to your imports, and use the following code in your main function:

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

Then open your browser and visit 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 NewServer to obtain a Server instance. Both the Server.Index and Server.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

Index

• Variables
• func Register(mux *http.ServeMux, opts ...Option) error
• func RegisterDefault(opts ...Option) error
• type BarMode
• type ErrReservedPlotName
  • func (e ErrReservedPlotName) Error() string
• type HoverOnType
• type Option
  • func Root(path string) Option
  • func SendFrequency(intv time.Duration) Option
  • func TimeseriesPlot(tsp TimeSeriesPlot) Option
• type Server
  • func NewServer(opts ...Option) (*Server, error)
  • func (s *Server) Index() http.HandlerFunc
  • func (s *Server) Register(mux *http.ServeMux)
  • func (s *Server) Ws() http.HandlerFunc
• type TimeSeries
• type TimeSeriesPlot
• type TimeSeriesPlotConfig
  • func (p TimeSeriesPlotConfig) Build() (TimeSeriesPlot, error)
• type TimeSeriesType

Variables

var (
	// ErrNoTimeSeries is returned when a user plot has no time series.
	ErrNoTimeSeries = errors.New("user plot must have at least one time series")

	// ErrEmptyPlotName is returned when a user plot has an empty name.
	ErrEmptyPlotName = errors.New("user plot name can't be empty")
)

Functions

func Register

func Register(mux *http.ServeMux, opts ...Option) error

Register registers the Statsviz HTTP handlers on the provided mux.

func RegisterDefault

func RegisterDefault(opts ...Option) error

RegisterDefault registers the Statsviz HTTP handlers on http.DefaultServeMux.

RegisterDefault should not be used in production.

Types

type BarMode

type BarMode string

BarMode determines how bars at the same location are displayed on a bar plot.

const (
	// Stack indicates that bars are stacked on top of one another.
	Stack BarMode = "stack"

	// Ggroup indicates that bars are plotted next to one another, centered
	// around the shared location.
	Group BarMode = "group"

	// Relative indicates that bars are stacked on top of one another, with
	// negative values below the axis and positive values above.
	Relative BarMode = "relative"

	// Overlay indicates that bars are plotted over one another.
	Overlay BarMode = "overlay"
)

type ErrReservedPlotName

type ErrReservedPlotName string

ErrReservedPlotName is returned when a reserved plot name is used for a user plot.

func (ErrReservedPlotName) Error

func (e ErrReservedPlotName) Error() string

type HoverOnType

type HoverOnType string

HoverOnType describes the type of hover effect on a time series plot.

const (
	// HoverOnPoints specifies that the hover effects highlights individual
	// points.
	HoverOnPoints HoverOnType = "points"

	// HoverOnPoints specifies that the hover effects highlights filled regions.
	HoverOnFills HoverOnType = "fills"

	// HoverOnPointsAndFills specifies that the hover effects highlights both
	// points and filled regions.
	HoverOnPointsAndFills HoverOnType = "points+fills"
)

type Option

type Option func(*Server) error

Option is a configuration option for the Server.

func Root

func Root(path string) Option

Root changes the root path of the Statsviz user interface. The default is "/debug/statsviz".

func SendFrequency

func SendFrequency(intv time.Duration) Option

SendFrequency changes the interval between successive acquisitions of metrics and their sending to the user interface. The default interval is one second.

func TimeseriesPlot

func TimeseriesPlot(tsp TimeSeriesPlot) Option

TimeseriesPlot adds a new time series plot to Statsviz. This options can be added multiple times.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is the core component of Statsviz. It collects and periodically updates metrics data and provides two essential HTTP handlers:

• the Index handler serves Statsviz user interface, allowing you to visualize runtime metrics on your browser.
• The Ws handler establishes a WebSocket connection allowing the connected browser to receive metrics updates from the server.

The zero value is not a valid Server, use NewServer to create a valid one.

func NewServer

func NewServer(opts ...Option) (*Server, error)

NewServer constructs a new Statsviz Server with the provided options, or the default settings.

Note that once the server is created, its HTTP handlers needs to be registered with some HTTP server. You can either use the Register method or register yourself the Index and Ws handlers.

func (*Server) Index

func (s *Server) Index() http.HandlerFunc

Index returns the index handler, which responds with the Statsviz user interface HTML page. By default, the handler is served at the path specified by the root. Use [WithRoot] to change the path.

func (*Server) Register

func (s *Server) Register(mux *http.ServeMux)

Register registers the Statsviz HTTP handlers on the provided mux.

func (*Server) Ws

func (s *Server) Ws() http.HandlerFunc

Ws returns the WebSocket handler used by Statsviz to send application metrics. The underlying net.Conn is used to upgrade the HTTP server connection to the WebSocket protocol.

type TimeSeries

type TimeSeries struct {
	// Name is the name identifying this time series in the user interface.
	Name string

	// UnitFmt is the d3-format string used to format the numbers of this time
	// series in the user interface. See https://github.com/d3/d3-format.
	Unitfmt string

	// HoverOn configures whether the hover effect highlights individual points
	// or do they highlight filled regions, or both. Defaults to HoverOnFills.
	HoverOn HoverOnType

	// Type is the time series type, either [Scatter] or [Bar]. default: [Scatter].
	Type TimeSeriesType

	// GetValue specifies the function called to get the value of this time
	// series.
	GetValue func() float64
}

A TimeSeries describes a single time series of a plot.

type TimeSeriesPlot

type TimeSeriesPlot struct {
	// contains filtered or unexported fields
}

TimeSeriesPlot is an opaque type representing a timeseries plot. A plot can be created with TimeSeriesPlotConfig.Build.

type TimeSeriesPlotConfig

type TimeSeriesPlotConfig struct {
	// Name is the plot name, it must be unique.
	Name string

	// Title is the plot title, shown above the plot.
	Title string

	// Type is either [Scatter] or [Bar]. default: [Scatter].
	Type TimeSeriesType

	// BarMode is either [Stack], [Group], [Relative] or [Overlay].
	// default: [Group].
	BarMode BarMode

	// Tooltip is the html-aware text shown when the user clicks on the plot
	// Info icon.
	InfoText string

	// YAxisTitle is the title of Y axis.
	YAxisTitle string

	// YAxisTickSuffix is the suffix added to tick values.
	YAxisTickSuffix string

	// Series contains the time series shown on this plot, there must be at
	// least one.
	Series []TimeSeries
}

TimeSeriesPlotConfig describes the configuration of a time series plot.

func (TimeSeriesPlotConfig) Build

func (p TimeSeriesPlotConfig) Build() (TimeSeriesPlot, error)

Build validates the configuration and builds a time series plot for it

type TimeSeriesType

type TimeSeriesType string

TimeSeriesType describes the type of a time series plot.

const (
	// Scatter is a time series plot made of lines.
	Scatter TimeSeriesType = "scatter"

	// Bar is a time series plot made of bars.
	Bar TimeSeriesType = "bar"
)