Visualize real time plots of your Go program runtime/metrics including heap, objects, goroutines, GC pauses, scheduler and more.
This fork is maintained by PinableAgents and is based on arl/statsviz. The logo and documentation screenshots below are hosted by the upstream project.
Get the latest version:
go get github.com/PinableAgents/statsviz@latest
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
History is opt-in. Programs that do not import history/sqlite do not link the
SQLite driver. To retain metrics across browser refreshes and normal process
restarts, open a dedicated database file and pass the store to History:
store, err := sqlitehistory.Open("/var/lib/myapp/statsviz.db", sqlitehistory.Options{
Retention: 7 * 24 * time.Hour,
})
if err != nil { /* handle error */ }
srv, err := statsviz.NewServer(statsviz.History(store))
if err != nil {
_ = store.Close()
/* handle error */
}
appMux := http.NewServeMux()
// Register on the application's existing mux.
srv.Register(appMux)
// 关闭时先停止采集并刷新队列。Store 由调用方持有，必须等
// Server.Close 返回后再关闭。
if err := srv.Close(); err != nil { /* handle flush error */ }
if err := store.Close(); err != nil { /* handle close error */ }For a diagnostics listener on its own configurable port, use a dedicated mux and HTTP server. Keeping this listener on loopback also avoids exposing runtime metrics on the public application listener:
statsMux := http.NewServeMux()
srv.Register(statsMux)
statsAddr := os.Getenv("STATSVIZ_ADDR")
if statsAddr == "" {
statsAddr = "127.0.0.1:8095"
}
statsHTTP := &http.Server{
Addr: statsAddr,
Handler: statsMux,
}
go func() {
if err := statsHTTP.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
log.Printf("statsviz HTTP server: %v", err)
}
}()Import the adapter as
sqlitehistory "github.com/PinableAgents/statsviz/history/sqlite". The default
retention window is seven days; the query layer clips results to retained data.
The database path is chosen by the application, and its parent directory is
created when needed. See _example/history for a complete
server with configurable address and database path.
With history enabled, use “查看历史” in the top bar to open the history controls: 1h, 6h, 24h and 7d presets, custom start/end times, a timeline slider, and actual sample details. Historical views stay fixed while collection continues; use “返回实时” to collapse the controls and restore the previous live time range. Zooming or panning a plot, or inspecting a sample, also opens the history controls. Long ranges use persisted rollups and adapt their resolution to the response budget, while point queries read the original snapshots. See the SQLite history design for storage limits, aggregation semantics and validation results. The opt-in capacity validation tool builds a full seven-day fixture and records storage and query measurements.
The registered HTTP endpoints follow the configured Root (the default paths
are shown below). All timestamps are UTC Unix milliseconds and range intervals
are left-closed, right-open:
GET /debug/statsviz/history/metaGET /debug/statsviz/history/range?from=...&to=...&run_id=...&max_points=1500&plots=...GET /debug/statsviz/history/point?at=...&run_id=...&tolerance_ms=...
One database file supports one collecting process at a time. Samples already committed survive normal restarts, while samples still in the in-memory queue can be lost after a crash or forced termination. SQLite normally reuses freed pages, so the database file may remain near its historical high-water size even after old samples expire. Retention is bounded by available disk space; it is not an unconditional storage guarantee.
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 funcExamples 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:
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.
Check out the API reference on pkg.go.dev.
Use the language selector in the top toolbar to switch between English and Simplified Chinese. The initial language follows your browser preferences; your selection is saved locally. Controls, chart tooltips, plot descriptions, and history details follow the selected language. Go API names and metric paths retain their original spelling.
Click a chart or query an actual sample to view its details in a scrollable dialog. Close it with the close button, Escape, or a click outside the dialog.
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.
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.
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.
Either use GitHub's discussions or come to say hi and ask a live question on #statsviz channel on Gopher's slack.
Please use issues for bugs and feature requests.
Pull-requests are always welcome!
More details in CONTRIBUTING.md.
See CHANGELOG.md.
See LICENSE