README

go.dev reference Test Actions Status Go Report Card codecov

Statsviz

Instant live visualization of your Go application runtime statistics (GC, MemStats, etc.).

  • Import "github.com/arl/statsviz"
  • Register statsviz HTTP handlers
  • Start your program
  • Open your browser at http://host:port/debug/statsviz
  • Enjoy...

How does it work?

What statsviz does is actually quite simple...

It's composed of 2 HTTP handlers.

When the first one is called(by default /debug/statsviz), it serves an html/js user interface showing some plots, initially empty, in your browser.

The browser then connects to statsviz second HTTP handler. The second one upgrades the connection to the websocket protocol and starts a goroutine that periodically calls runtime.ReadMemStats.

Stats are sent, via websocket, to the user interface, which inturn, updates the plots.

Stats are stored in-browser inside a circular buffer which keep tracks of 60 datapoints, so one minute-worth of data by default. You can change the frequency at which stats are sent by passing SendFrequency to Register.

Usage

go get -u github.com/arl/statsviz

Either Register statsviz HTTP handlers with the http.ServeMux you're using (preferred method):

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

Or register them with the http.DefaultServeMux:

statsviz.RegisterDefault()

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))
}()

By default the handled path is /debug/statsviz/.

Then open your browser at http://localhost:6060/debug/statsviz/

Examples

Using http.DefaultServeMux:

Using your own http.ServeMux:

Serve statsviz on /foo/bar instead of default /debug/statsviz:

Serve on https (and wss for websocket):

With gorilla/mux router:

Using labstack/echo router:

With gin-gonic/gin web framework:

With go-chi/chi router:

Plots

On the plots where it matters, garbage collections are shown as vertical lines.

Heap
Heap plot image
MSpans / MCaches
MSpan/MCache plot image
Size classes heatmap
Size classes heatmap image
Objects
Objects plot image
Goroutines
Goroutines plot image
GC/CPU fraction
GC/CPU fraction plot image

Contributing

Pull-requests are welcome! More details in CONTRIBUTING.md

Roadmap

  • add stop-the-world duration heatmap
  • increase data retention
  • light/dark mode selector
  • plot image export as png
  • save timeseries to disk
  • load from disk previously saved timeseries

Changelog

See CHANGELOG.md.

License

Expand ▾ Collapse ▴

Documentation

Overview

    Package statsviz serves via its HTTP server an HTML page displaying live visualization of the application runtime statistics.

    Either Register statsviz HTTP handlers with the http.ServeMux you're using (preferred method):

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

    Or register them with the http.DefaultServeMux:

    statsviz.RegisterDefault()
    

    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))
    }()
    

    Index

    Constants

    This section is empty.

    Variables

    View Source
    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.

      View Source
      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.Handler

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

                      Directories

                      Path Synopsis
                      chi
                      gin
                      mux