• Stars
    star
    3,128
  • Rank 13,802 (Top 0.3 %)
  • Language
    Go
  • License
    MIT License
  • Created almost 4 years ago
  • Updated 20 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

๐Ÿš€ Visualise your Go program runtime metrics in real time in the browser

go.dev reference Latest tag Mentioned in Awesome Go

Test Actions Status Test Actions Status codecov

Statsviz

Statsviz Gopher Logo statsviz ui


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


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:

menu

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

menu

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

Heap (details)

heap-details

Live Objects in Heap

live-objects

Live Bytes in Heap

live-bytes

MSpan/MCache

mspan-mcache

Memory classes

memory-classes

Goroutines

goroutines

Size Classes

size-classes

GC Scan

gc-scan

GC Cycles

gc-cycles

Stop-the-world Pause Latencies

gc-pauses

CPU Classes (GC)

cpu-classes-gc

Time Goroutines Spend in 'Runnable' state

runnable-time

Time Goroutines Spend Blocked on Mutexes

mutex-wait

Starting Size of Goroutines Stacks

gc-stack-size

Goroutine Scheduling Events

sched-events

CGO Calls

cgo

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:

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

More Repositories

1

gitmux

๐Ÿ’ป Git in your tmux status bar
Go
549
star
2

tmux-gitbar

Git in your tmux status bar
Shell
171
star
3

go-rquad

๐Ÿ“Œ State of the art point location and neighbour finding algorithms for region quadtrees, in Go
Go
131
star
4

go-detour

๐Ÿ‘พ Navigation mesh pathfinding and spatial reasoning library
Go
123
star
5

macdeployqtfix

To bundle a Qt application on Mac OSX, there is macdeployqt. To finish the job there is macdeployqtfix! โœ…
Python
60
star
6

golq

๐Ÿ“ก 2D locality queries in Go
Go
31
star
7

assertgo

Conditionally compiled assertions in Go
Go
18
star
8

scripts

this is my collection of bash scripts for everyday use
Shell
15
star
9

dotfiles

My dotfiles config... Feel free to use
Shell
8
star
10

udpnet

Game networking library in Go, based on UDP
Go
6
star
11

gogeo

Geometry library in Go
Go
5
star
12

gitstatus

Retrieve the Git status of a working tree, in Go.
Go
5
star
13

bitfield

Go-generate code to emulate C bit fields
Go
5
star
14

gioexp

Experiments with Gio, the cross-platform gui for Go
Go
3
star
15

evolve

Evolutionary Computation Framework
Go
3
star
16

fastlfu

LFU cache with O(1) runtime complexity for all operations: insertion, access and deletion (eviction). In Go.
Go
3
star
17

imgtools

Utilities for working with images in Go, completing the standard image package.
Go
3
star
18

gotypes

Automatically generate Go code from Go structures
Go
2
star
19

urlserv

URL shortener demo for First Steps with Go training
Go
2
star
20

iolib2

Output device abstraction. Mask device differences (serial port, LPT, file, ethernet, etc.). Extendable
Go
2
star
21

serve

Serves the content of a directory as HTTP.
Go
2
star
22

gencli

Go-generate your urfave/cli flags from a structure
Go
1
star
23

go-gencon

Go Generic Containers - Reduce boilerplate by generating containers for your datastructures
Go
1
star
24

gsettings-upd

A systemd service that updates gsettings values
Go
1
star
25

get-up-and-go

Solutions for exercices of the Tour of Go
Go
1
star
26

training

Firs steps with go (Go introduction training)
Go
1
star
27

bitstring

Go Bitstring module
Go
1
star
28

artificial

Artificial art framework and experiement
Go
1
star
29

zsort

Useful additions to the sort package
Go
1
star
30

beggining-with-go

Go
1
star
31

monitoring

Monitoring workshop source code
Go
1
star
32

math32

32 bits wrapper around the standard go math package
Go
1
star
33

opencog-workbench

A tool to assist in the control and visualization of the OpenCog AtomSpace. It should facilitate the comprehension of AGI dynamics and allow a researcher to guide, tune, and understand the various mind processes in action, handle the parsing of log files and dynamic configuration of a running OpenCog instance. (developed with Angular, Bootstrap)
JavaScript
1
star