README
¶
Statsviz
Visualize real time plots of your Go program runtime metrics, including heap, objects, goroutines, GC pauses, scheduler and more, in your browser.
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/statsvizrather than/debug/statsviz - you want Statsviz under
https://rather thanhttp:// - 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.DefaultServeMuxor your ownhttp.ServeMux - wrap HTTP handler behind a middleware
- register the web page at
/foo/barinstead of/debug/statsviz - use
https://rather thanhttp:// - register Statsviz handlers with various Go HTTP libraries/frameworks:
How Does That Work?
Statsviz is made of two parts:
-
The
Wsserves 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
Indexhttp handler serves Statsviz user interface at/debug/statsvizat 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
Each plot belongs to one or more categories. The category selector allows you to filter the visible plots by categories.
Use the time range selector to define the visualized time span.
Show or hide the vertical lines representing garbage collection events.
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
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.NewServer() ss.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 ¶
Constants ¶
This section is empty.
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 RegisterDefault ¶
RegisterDefault registers the Statsviz HTTP handlers on http.DefaultServeMux.
RegisterDefault should not be used in production.
Types ¶
type BarMode ¶ added in v0.6.0
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 ¶ added in v0.6.0
type ErrReservedPlotName string
ErrReservedPlotName is returned when a reserved plot name is used for a user plot.
func (ErrReservedPlotName) Error ¶ added in v0.6.0
func (e ErrReservedPlotName) Error() string
type HoverOnType ¶ added in v0.6.0
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 ¶ added in v0.6.0
Option is a configuration option for the Server.
func Root ¶ added in v0.2.0
Root changes the root path of the Statsviz user interface. The default is "/debug/statsviz".
func SendFrequency ¶ added in v0.2.0
SendFrequency changes the interval between successive acquisitions of metrics and their sending to the user interface. The default interval is one second.
func TimeseriesPlot ¶ added in v0.6.0
func TimeseriesPlot(tsp TimeSeriesPlot) Option
TimeseriesPlot adds a new time series plot to Statsviz. This options can be added multiple times.
type Server ¶ added in v0.6.0
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 a valid Server, with default options.
func NewServer ¶ added in v0.6.0
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 ¶ added in v0.6.0
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 ¶ added in v0.6.0
Register registers the Statsviz HTTP handlers on the provided mux.
func (*Server) Ws ¶ added in v0.6.0
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 ¶ added in v0.6.0
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 ¶ added in v0.6.0
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 ¶ added in v0.6.0
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 ¶ added in v0.6.0
func (p TimeSeriesPlotConfig) Build() (TimeSeriesPlot, error)
Build validates the configuration and builds a time series plot for it
type TimeSeriesType ¶ added in v0.6.0
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" )
Source Files
Directories