Statsviz

https://pkg.go.dev/github.com/arl/statsviz
Admin
Statsviz visualizes real-time plots of Go program runtime metrics, including heap, objects,...
Tokens:5,454
Snippets:65
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Statsviz

Source: https://pkg.go.dev/github.com/arl/statsviz

Use the go get command to add the package to your project.

```bash
go get github.com/arl/statsviz@latest
```

--------------------------------

### Start HTTP Server for Statsviz

Source: https://pkg.go.dev/github.com/arl/statsviz

Start a background HTTP server to serve Statsviz if the application is not already running one.

```go
go func() {
    log.Println(http.ListenAndServe("localhost:8080", nil))
}()
```

--------------------------------

### Obtain Statsviz Server Instance

Source: https://pkg.go.dev/github.com/arl/statsviz

Use NewServer to get a server instance for manual control over Index and Websocket handlers.

```go
srv, err := statsviz.NewServer(); // Create server or handle error
srv.Index()                       // UI (dashboard) http.HandlerFunc
srv.Ws()                          // Websocket http.HandlerFunc
```

--------------------------------

### Get UserPlot layout

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Returns the layout configuration for a user plot.

```go
func (up UserPlot) Layout() any
```

--------------------------------

### Initialize Assets Variable

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/static

Uses sync.OnceValue to lazily initialize and return the filesystem containing frontend assets from a zip archive.

```go
var Assets = sync.OnceValue(func() fs.FS {
	zr, err := zip.NewReader(bytes.NewReader(distzip), int64(len(distzip)))
	if err != nil {
		panic(fmt.Sprintf("error reading dist.zip: %s", err))
	}
	webFS, err := fs.Sub(zr, "dist")
	if err != nil {
		panic(fmt.Sprintf("error loading frontend assets: %s", err))
	}
	return webFS
})
```

--------------------------------

### Initialize Custom Statsviz Server

Source: https://pkg.go.dev/github.com/arl/statsviz

Use NewServer to manually access Index and Ws handlers for custom routing, middleware, or HTTPS configurations.

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

--------------------------------

### Manage Server Lifecycle and Handlers

Source: https://pkg.go.dev/github.com/arl/statsviz

Methods to create, register, and close the Statsviz server.

```go
func NewServer(opts ...Option) (*Server, error)
```

```go
func (s *Server) Close() error
```

```go
func (s *Server) Index() http.HandlerFunc
```

```go
func (s *Server) Register(mux *http.ServeMux)
```

```go
func (s *Server) Ws() http.HandlerFunc
```

--------------------------------

### Initialize List

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Creates a new List instance from a slice of UserPlot.

```go
func NewList(userPlots []UserPlot) (*List, error)
```

--------------------------------

### NewServer

Source: https://pkg.go.dev/github.com/arl/statsviz

Constructs a new Statsviz Server instance with optional configuration.

```APIDOC
## func NewServer(opts ...Option) (*Server, error)

### Description
Constructs a new Statsviz Server with the provided options, or the default settings. Once created, the HTTP handlers must be registered with an HTTP server.

### Parameters
- **opts** (...Option) - Optional - Configuration options for the server.
```

--------------------------------

### Configure Server Options

Source: https://pkg.go.dev/github.com/arl/statsviz

Functions to configure the Statsviz server, including root path, frequency, and custom plots.

```go
func Root(path string) Option
```

```go
func SendFrequency(intv time.Duration) Option
```

```go
func TimeseriesPlot(tsp TimeSeriesPlot) Option
```

--------------------------------

### Build Time Series Plot

Source: https://pkg.go.dev/github.com/arl/statsviz

Validates the configuration and constructs a TimeSeriesPlot instance.

```go
func (p TimeSeriesPlotConfig) Build() (TimeSeriesPlot, error)
```

--------------------------------

### Execute Work function

Source: https://pkg.go.dev/github.com/arl/statsviz/_example

Runs an infinite loop that generates memory allocations of varying sizes to create a demo effect.

```go
func Work()
```

--------------------------------

### Retrieve List configuration

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Returns the configuration object for the plot list.

```go
func (pl *List) Config() *Config
```

--------------------------------

### Define Option Type

Source: https://pkg.go.dev/github.com/arl/statsviz

Configuration option function type for the Server.

```go
type Option func(*Server) error
```

--------------------------------

### Register Statsviz with DefaultServeMux

Source: https://pkg.go.dev/github.com/arl/statsviz

Register Statsviz handlers with the default HTTP server. Avoid using this in production environments.

```go
ss := statsviz.NewServer()
ss.Register(http.DefaultServeMux)
```

--------------------------------

### Define Server Struct

Source: https://pkg.go.dev/github.com/arl/statsviz

The core component for collecting metrics and providing HTTP handlers.

```go
type Server struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### Register Statsviz with ServeMux

Source: https://pkg.go.dev/github.com/arl/statsviz

Register Statsviz handlers with a custom http.ServeMux instance.

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

--------------------------------

### Convert RGB to String

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Utility function to format RGB values as a string.

```go
func RGBString(r, g, b uint8) string
```

--------------------------------

### statsviz.NewServer

Source: https://pkg.go.dev/github.com/arl/statsviz

Creates a new Statsviz server instance, allowing for more control over HTTP handlers and middleware integration.

```APIDOC
## func NewServer(opts ...Option) (*Server, error)

### Description
Creates a new Server instance. This is useful when you need to place Statsviz handlers behind custom middleware or use specific HTTP frameworks.

### Parameters
- **opts** (...Option) - Optional - Configuration options for the server.

### Methods
- **Index() http.HandlerFunc**: Returns the handler for the UI dashboard.
- **Ws() http.HandlerFunc**: Returns the handler for the websocket connection.
- **Register(mux *http.ServeMux)**: Registers the server's handlers on the provided mux.
- **Close() error**: Closes the server instance.
```

--------------------------------

### Register Statsviz with http.ServeMux

Source: https://pkg.go.dev/github.com/arl/statsviz

Register the default Statsviz handlers to an existing HTTP multiplexer.

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

go func() {
    log.Println(http.ListenAndServe("localhost:8080", mux))
}()
```

--------------------------------

### Register Function Signatures

Source: https://pkg.go.dev/github.com/arl/statsviz

Function signatures for registering Statsviz handlers.

```go
func Register(mux *http.ServeMux, opts ...Option) error
```

```go
func RegisterDefault(opts ...Option) error
```

--------------------------------

### Define Plot Configuration

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Structures for configuring plot series and events.

```go
type Config struct {
	// Series contains the plots we want to show and how we want to show them.
	Series []any `json:"series"`
	// Events contains a list of 'events time series' names. Series with
	// these names must be sent alongside other series. An event time series
	// is just made of timestamps with no associated value, each of which
	// gets plotted as a vertical line over another plot.
	Events []string `json:"events"`
}
```

--------------------------------

### Define TimeSeries and Plot Structures

Source: https://pkg.go.dev/github.com/arl/statsviz

Structures for defining individual time series data and plot configurations.

```go
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
}
```

```go
type TimeSeriesPlot struct {
	// contains filtered or unexported fields
}
```

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

--------------------------------

### Server.Index

Source: https://pkg.go.dev/github.com/arl/statsviz

Returns the HTTP handler for the Statsviz user interface.

```APIDOC
## func (*Server) Index() http.HandlerFunc

### Description
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 configuration.
```

--------------------------------

### Define HoverOnPointsAndFills

Source: https://pkg.go.dev/github.com/arl/statsviz

Specifies that hover effects should highlight both points and filled regions.

```go
HoverOnPointsAndFills HoverOnType = "points+fills"
```

--------------------------------

### Server.Ws

Source: https://pkg.go.dev/github.com/arl/statsviz

Returns the WebSocket handler for metrics updates.

```APIDOC
## func (*Server) Ws() http.HandlerFunc

### Description
Returns the WebSocket handler used by Statsviz to send application metrics to the connected browser.
```

--------------------------------

### func Work()

Source: https://pkg.go.dev/github.com/arl/statsviz/_example

The Work function loops forever, generating allocations of various sizes to create artificial work for a demo effect.

```APIDOC
## func Work()

### Description
Work loops forever, generating allocations of various sizes, in order to create artificial work for a nice 'demo effect'.

### Signature
`func Work()`
```

--------------------------------

### Define Heatmap Structures

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Data structures for defining heatmap plots, including hover information and layout.

```go
type HeapmapHover struct {
	YName string `json:"yname"`
	YUnit string `json:"yunit"` // 'duration', 'bytes' or custom
	ZName string `json:"zname"`
}
```

```go
type Heatmap struct {
	Name       string          `json:"name"`
	Tags       []string        `json:"tags"`
	Title      string          `json:"title"`
	Type       string          `json:"type"`
	UpdateFreq int             `json:"updateFreq"`
	InfoText   string          `json:"infoText"`
	Events     string          `json:"events"`
	Layout     HeatmapLayout   `json:"layout"`
	Colorscale []WeightedColor `json:"colorscale"`
	Buckets    []float64       `json:"buckets"`
	CustomData []float64       `json:"custom_data"`
	Hover      HeapmapHover    `json:"hover"`
	Metrics    []string        `json:"metrics"`
}
```

```go
type HeatmapLayout struct added in v0.6.0
{
	YAxis HeatmapYaxis `json:"yaxis"`
}
```

--------------------------------

### Server.Register

Source: https://pkg.go.dev/github.com/arl/statsviz

Registers the Statsviz HTTP handlers on a provided ServeMux.

```APIDOC
## func (*Server) Register(mux *http.ServeMux)

### Description
Registers the Statsviz HTTP handlers (Index and Ws) on the provided mux. This must be called once per application.

### Parameters
- **mux** (*http.ServeMux) - Required - The HTTP multiplexer to register handlers on.
```

--------------------------------

### Marshal WeightedColor to JSON

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Implements the json.Marshaler interface for WeightedColor.

```go
func (c WeightedColor) MarshalJSON() ([]byte, error)
```

--------------------------------

### Server.Close

Source: https://pkg.go.dev/github.com/arl/statsviz

Releases resources used by the Server.

```APIDOC
## func (*Server) Close() error

### Description
Releases all resources used by the Server instance.
```

--------------------------------

### func (TimeSeriesPlotConfig) Build

Source: https://pkg.go.dev/github.com/arl/statsviz

Validates the configuration and builds a time series plot for the provided TimeSeriesPlotConfig.

```APIDOC
## func (TimeSeriesPlotConfig) Build

### Description
Validates the configuration and builds a time series plot for it.

### Signature
`func (p TimeSeriesPlotConfig) Build() (TimeSeriesPlot, error)`

### Returns
- **TimeSeriesPlot** - The constructed time series plot.
- **error** - An error object if validation fails.
```

--------------------------------

### Define List structure

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Holds the collection of plots known to statsviz.

```go
type List struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### statsviz.Register

Source: https://pkg.go.dev/github.com/arl/statsviz

Registers the Statsviz HTTP handlers on the provided http.ServeMux. This should be called once per application.

```APIDOC
## func Register(mux *http.ServeMux, opts ...Option) error

### Description
Registers the Statsviz HTTP handlers on the provided mux. This function must be called once per application.

### Parameters
- **mux** (*http.ServeMux) - Required - The HTTP ServeMux to register handlers on.
- **opts** (...Option) - Optional - Configuration options for the Statsviz server.
```

--------------------------------

### Define ScatterLayout structure

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Configures the layout properties for a scatter plot.

```go
type ScatterLayout struct {
	Yaxis   ScatterYAxis `json:"yaxis"`
	BarMode string       `json:"barmode"`
}
```

--------------------------------

### Define HoverOnType Constants

Source: https://pkg.go.dev/github.com/arl/statsviz

Constants defining hover effects on time series plots.

```go
type HoverOnType string

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

--------------------------------

### Write plot data to writer

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Serializes plot data points into a JSON object and writes them to the provided io.Writer.

```go
func (pl *List) WriteTo(w io.Writer) (int64, error)
```

--------------------------------

### TimeSeriesPlotConfig Structure

Source: https://pkg.go.dev/github.com/arl/statsviz

Defines the configuration for a time series plot, requiring at least one TimeSeries entry.

```go
// Series contains the time series shown on this plot, there must be at
	// least one.
	Series []TimeSeries
}
```

--------------------------------

### Define UserPlot structure

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

A container for either a scatter or heatmap user plot.

```go
type UserPlot struct {
	Scatter *ScatterUserPlot
	Heatmap *HeatmapUserPlot
}
```

--------------------------------

### Define HeatmapUserPlot structure

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Represents a user-defined heatmap plot configuration.

```go
type HeatmapUserPlot struct {
	Plot Heatmap
}
```

--------------------------------

### Define Scatter structure

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Defines the properties and layout for a scatter plot.

```go
type Scatter struct {
	Name       string        `json:"name"`
	Tags       []string      `json:"tags"`
	Title      string        `json:"title"`
	Type       string        `json:"type"`
	UpdateFreq int           `json:"updateFreq"`
	InfoText   string        `json:"infoText"`
	Events     string        `json:"events"`
	Layout     ScatterLayout `json:"layout"`
	Subplots   []Subplot     `json:"subplots"`
	Metrics    []string      `json:"metrics"`
}
```

--------------------------------

### Define BarMode Constants

Source: https://pkg.go.dev/github.com/arl/statsviz

Constants defining how bars are displayed on a bar plot.

```go
type BarMode string

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"
)
```

--------------------------------

### Define ScatterUserPlot structure

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Combines a scatter plot definition with its data-fetching functions.

```go
type ScatterUserPlot struct {
	Plot  Scatter
	Funcs []func() float64
}
```

--------------------------------

### Define HeatmapYaxis structure

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Configures the Y-axis settings for a heatmap plot.

```go
type HeatmapYaxis struct {
	Title    string    `json:"title"`
	TickMode string    `json:"tickmode"`
	TickVals []float64 `json:"tickvals"`
	TickText []float64 `json:"ticktext"`
}
```

--------------------------------

### Define Statsviz Variables

Source: https://pkg.go.dev/github.com/arl/statsviz

Error variables used for user-defined plots.

```go
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")
)
```

--------------------------------

### Define WeightedColor structure

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Maps a float value to a specific RGBA color.

```go
type WeightedColor struct {
	Value float64
	Color color.RGBA
}
```

--------------------------------

### TimeSeriesType Definition and Constants

Source: https://pkg.go.dev/github.com/arl/statsviz

Defines the type for time series plots and available constants for scatter and bar plot styles.

```go
type TimeSeriesType string
```

```go
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"
)
```

--------------------------------

### Check Reserved Plot Names

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Validates if a plot name is reserved for internal Statsviz use.

```go
func IsReservedPlotName(name string) bool
```

--------------------------------

### Define Weighted Color Shades

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Predefined color scales for plots using WeightedColor structures.

```go
var BlueShades = []WeightedColor{
	{Value: 0.0, Color: color.RGBA{0xea, 0xf8, 0xfd, 1}},
	{Value: 0.1, Color: color.RGBA{0xbf, 0xeb, 0xfa, 1}},
	{Value: 0.2, Color: color.RGBA{0x94, 0xdd, 0xf6, 1}},
	{Value: 0.3, Color: color.RGBA{0x69, 0xd0, 0xf2, 1}},
	{Value: 0.4, Color: color.RGBA{0x3f, 0xc2, 0xef, 1}},
	{Value: 0.5, Color: color.RGBA{0x14, 0xb5, 0xeb, 1}},
	{Value: 0.6, Color: color.RGBA{0x10, 0x94, 0xc0, 1}},
	{Value: 0.7, Color: color.RGBA{0x0d, 0x73, 0x96, 1}},
	{Value: 0.8, Color: color.RGBA{0x09, 0x52, 0x6b, 1}},
	{Value: 0.9, Color: color.RGBA{0x05, 0x31, 0x40, 1}},
	{Value: 1.0, Color: color.RGBA{0x02, 0x10, 0x15, 1}},
}
```

```go
var GreenShades = []WeightedColor{
	{Value: 0.0, Color: color.RGBA{0xed, 0xf7, 0xf2, 0}},
	{Value: 0.1, Color: color.RGBA{0xc9, 0xe8, 0xd7, 0}},
	{Value: 0.2, Color: color.RGBA{0xa5, 0xd9, 0xbc, 0}},
	{Value: 0.3, Color: color.RGBA{0x81, 0xca, 0xa2, 0}},
	{Value: 0.4, Color: color.RGBA{0x5e, 0xbb, 0x87, 0}},
	{Value: 0.5, Color: color.RGBA{0x44, 0xa1, 0x6e, 0}},
	{Value: 0.6, Color: color.RGBA{0x35, 0x7e, 0x55, 0}},
	{Value: 0.7, Color: color.RGBA{0x26, 0x5a, 0x3d, 0}},
	{Value: 0.8, Color: color.RGBA{0x17, 0x36, 0x25, 0}},
	{Value: 0.9, Color: color.RGBA{0x08, 0x12, 0x0c, 0}},
	{Value: 1.0, Color: color.RGBA{0x00, 0x00, 0x00, 0}},
}
```

```go
var PinkShades = []WeightedColor{
	{Value: 0.0, Color: color.RGBA{0xfe, 0xe7, 0xf3, 1}},
	{Value: 0.1, Color: color.RGBA{0xfc, 0xb6, 0xdc, 1}},
	{Value: 0.2, Color: color.RGBA{0xf9, 0x85, 0xc5, 1}},
	{Value: 0.3, Color: color.RGBA{0xf7, 0x55, 0xae, 1}},
	{Value: 0.4, Color: color.RGBA{0xf5, 0x24, 0x96, 1}},
	{Value: 0.5, Color: color.RGBA{0xdb, 0x0a, 0x7d, 1}},
	{Value: 0.6, Color: color.RGBA{0xaa, 0x08, 0x61, 1}},
	{Value: 0.7, Color: color.RGBA{0x7a, 0x06, 0x45, 1}},
	{Value: 0.8, Color: color.RGBA{0x49, 0x03, 0x2a, 1}},
	{Value: 0.9, Color: color.RGBA{0x18, 0x01, 0x0e, 1}},
	{Value: 1.0, Color: color.RGBA{0x00, 0x00, 0x00, 1}},
}
```

--------------------------------

### Define ScatterYAxis structure

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Configures the Y-axis for a scatter plot.

```go
type ScatterYAxis struct {
	Title      string `json:"title"`
	TickSuffix string `json:"ticksuffix"`
}
```

--------------------------------

### Define ErrReservedPlotName Type and Method

Source: https://pkg.go.dev/github.com/arl/statsviz

Type definition and error method for reserved plot names.

```go
type ErrReservedPlotName string
```

```go
func (e ErrReservedPlotName) Error() string
```

--------------------------------

### Define Subplot structure

Source: https://pkg.go.dev/github.com/arl/statsviz/internal/plot

Defines an individual subplot within a larger plot.

```go
type Subplot struct {
	Name       string `json:"name"`
	Unitfmt    string `json:"unitfmt"`
	StackGroup string `json:"stackgroup"`
	HoverOn    string `json:"hoveron"`
	Color      string `json:"color"`
	Type       string `json:"type"`
}
```
Tokens:
Raw