Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/arl/statsviz

🚀 Visualise your Go program runtime metrics in real time in the browser
https://github.com/arl/statsviz

garbage-collector go golang golang-library hacktoberfest live metrics monitoring plots runtime stats visualization

Last synced: 4 days ago
JSON representation

🚀 Visualise your Go program runtime metrics in real time in the browser

Host: GitHub
URL: https://github.com/arl/statsviz
Owner: arl
License: mit
Created: 2020-08-14T00:00:41.000Z (over 4 years ago)
Default Branch: main
Last Pushed: 2024-04-28T10:12:23.000Z (9 months ago)
Last Synced: 2024-12-31T14:11:50.396Z (11 days ago)
Topics: garbage-collector, go, golang, golang-library, hacktoberfest, live, metrics, monitoring, plots, runtime, stats, visualization
Language: Go
Homepage:
Size: 6.75 MB
Stars: 3,239
Watchers: 34
Forks: 124
Open Issues: 11
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

awesome-go - statsviz - Live visualization of your Go application runtime statistics. (Performance / HTTP Clients)
zero-alloc-awesome-go - statsviz - Live visualization of your Go application runtime statistics. (Performance / HTTP Clients)
my-awesome - arl/statsviz - collector,go,golang,golang-library,hacktoberfest,live,metrics,monitoring,plots,runtime,stats,visualization pushed_at:2024-04 star:3.2k fork:0.1k 🚀 Visualise your Go program runtime metrics in real time in the browser (Go)
awesome-repositories - arl/statsviz - 🚀 Visualise your Go program runtime metrics in real time in the browser (Go)
go-awesome - statsviz - View runtime statistics of Go application (GC, MemStats, etc.) in real-time in browser (Open source library / Debugging)
awesome-go - statsviz - Live visualization of your Go application runtime statistics. Stars:`3.2K`. (Performance / HTTP Clients)
awesome-golang-repositories - statsviz
awesome-go-extra - statsviz - 08-14T00:00:41Z|2022-08-24T20:42:34Z| (Performance / HTTP Clients)
dynamic-analysis - statsviz

README

        [![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=round-square)](https://pkg.go.dev/github.com/arl/statsviz)

[![Latest tag](https://img.shields.io/github/tag/arl/statsviz.svg)](https://github.com/arl/statsviz/tag/)

[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)

[![Test Actions Status](https://github.com/arl/statsviz/workflows/Tests-linux/badge.svg)](https://github.com/arl/statsviz/actions)

[![Test Actions Status](https://github.com/arl/statsviz/workflows/Tests-others/badge.svg)](https://github.com/arl/statsviz/actions)

[![codecov](https://codecov.io/gh/arl/statsviz/branch/main/graph/badge.svg)](https://codecov.io/gh/arl/statsviz)

# Statsviz



  

  






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



- [Statsviz](#statsviz)

  - [Install](#install)

  - [Usage](#usage)

  - [Advanced Usage](#advanced-usage)

  - [How Does That Work?](#how-does-that-work)

  - [Documentation](#documentation)

    - [Go API](#go-api)

    - [User interface](#user-interface)

    - [Plots](#plots)

    - [User Plots](#user-plots)

  - [Examples](#examples)

  - [Questions / Troubleshooting](#questions--troubleshooting)

  - [Contributing](#contributing)

  - [Changelog](#changelog)

  - [License: MIT](#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`.

```go

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

```go

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](_example) 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](https://pkg.go.dev/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](https://pkg.go.dev/github.com/arl/statsviz#section-documentation).

### 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](_example/userplots/main.go).

## Examples

Check out the [\_example](./_example/README.md) 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](https://github.com/labstack/echo/)

  - [fasthttp](https://github.com/valyala/fasthttp)

  - [fiber](https://github.com/gofiber/fiber/)

  - [gin](https://github.com/gin-gonic/gin)

  - and many others thanks to many contributors!

## Questions / Troubleshooting

Either use GitHub's [discussions](https://github.com/arl/statsviz/discussions) or come to say hi and ask a live question on [#statsviz channel on Gopher's slack](https://gophers.slack.com/archives/C043DU4NZ9D).

## Contributing

Please use [issues](https://github.com/arl/statsviz/issues/new/choose) for bugs and feature requests.  

Pull-requests are always welcome!  

More details in [CONTRIBUTING.md](CONTRIBUTING.md).

## Changelog

See [CHANGELOG.md](./CHANGELOG.md).

## License: MIT

See [LICENSE](LICENSE)