Documentation
¶
Overview ¶
Package statc implements runtime process stats and status reporting.
It provides the basics (timers, gauges, counters), stats sinks, interfaces for fetching current stats, and so on.
Index ¶
- func CleanPath(path string) string
- func EscapePath(path string) string
- func JoinNoEscape(parts ...string) string
- func JoinPath(parent string, parts ...string) string
- func RegisterFormatter(name string, nf NewFormatter)
- type Adder
- type BoolGauge
- type Config
- type Counter
- type FloatGauge
- type Formatter
- type Gauge
- type HTTPEndpoint
- type HTTPMuxer
- type HTTPResp
- type JSONFormat
- type LogstashFormat
- type Name
- type NewFormatter
- type OutputConfig
- type S
- func (s *S) AddLog(name string, l *clog.Ctx)
- func (s *S) AddSnapshotter(name Name, snapper Snapshotter)
- func (s *S) Name(name string) Name
- func (s *S) Names(names ...string) Name
- func (s *S) NewBoolGauge(name string) *BoolGauge
- func (s *S) NewCounter(name string, reset bool) *Counter
- func (s *S) NewFloatGauge(name string) *FloatGauge
- func (s *S) NewGauge(name string) *Gauge
- func (s *S) NewHTTPMuxer(name string) *HTTPMuxer
- func (s *S) NewStringGauge(name string) *StringGauge
- func (s *S) NewTimer(name string, sampPercent int) *Timer
- func (s *S) Prefixed(prefix string) *S
- func (s *S) Snapshot() (snap Snapshot)
- type Snapshot
- type Snapshotter
- type Stat
- type StringGauge
- type Timer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EscapePath ¶
EscapePath escapes all reserved characters in the given path. For example, if you have a path like "url/img.jpg", the "." presents a special problem, so the path becomes "url/img_jpg".
This might do more escapes in the future, so use this instead of strings.Replace().
func JoinNoEscape ¶
JoinNoEscape joins all parts together without escaping each part. This means that parts may contain ".".
func JoinPath ¶
JoinPath creates a stats path from multiple path elements. The parent element is left unescaped to allow for tacking on child paths.
func RegisterFormatter ¶
func RegisterFormatter(name string, nf NewFormatter)
RegisterFormatter adds a Filter to the list of filters
Types ¶
type Adder ¶
type Adder interface {
AddBool(name Name, val bool)
AddFloat(name Name, val float64)
AddInt(name Name, val int64)
AddString(name Name, val string)
}
An Adder is used to add stats to a snapshot. If no name is given, (that is Name{}), then the stat's name is used. If any other name is given, that will be used instead.
type BoolGauge ¶
type BoolGauge struct {
// contains filtered or unexported fields
}
A BoolGauge is a single bool value that can be set at will
type Config ¶
type Config struct {
// How often to take snapshots. Defaults to 10s.
SnapshotInterval ctime.HumanDuration
// Percent of HTTP requests to sample. Defaults to 10%. Range (0-100) for
// 0% - 100%.
HTTPSamplePercent int
// If memory stats should be included in reported statistics. Defaults to
// 60s; gathering these stats stops the world, so don't do this too often.
// Set to <0 to disable.
MemStatsInterval ctime.HumanDuration
// StatusKey is the key used to secure the HTTPMuxer's /_status endpoint
StatusKey string
// Where stats should be put
Outputs []OutputConfig
// contains filtered or unexported fields
}
Config sets up stats. It can be read in from a config file to allow for simpler configing.
type Counter ¶
type Counter struct {
// contains filtered or unexported fields
}
A Counter is used to count things
type FloatGauge ¶
type FloatGauge struct {
// contains filtered or unexported fields
}
A FloatGauge is a single float value that can be set at will
func (*FloatGauge) Get ¶
func (g *FloatGauge) Get() (v float64)
Get gets the current value of the gauge
func (*FloatGauge) Set ¶
func (g *FloatGauge) Set(v float64)
Set sets the current value of this gauge
func (*FloatGauge) Snapshot ¶
func (g *FloatGauge) Snapshot(a Adder)
Snapshot implements Snapshotter
type Formatter ¶
type Formatter interface {
// Format a snapshot
FormatSnap(snap Snapshot) ([]byte, error)
// Get the MimeType of data produced by this Formatter
MimeType() string
}
A Formatter formats a snapshot
type Gauge ¶
type Gauge struct {
// contains filtered or unexported fields
}
A Gauge is a single value that can be set at will
type HTTPEndpoint ¶
type HTTPEndpoint struct {
// contains filtered or unexported fields
}
An HTTPEndpoint is used for timing requests to an endpoint.
func (*HTTPEndpoint) Start ¶
func (he *HTTPEndpoint) Start(w http.ResponseWriter) *HTTPResp
Start timing the request
type HTTPMuxer ¶
type HTTPMuxer struct {
// Exposed so that you can set Options on it, use it as the server
// handler, etc. Any routes added directly here will have no stats
// recorded for them.
R *httprouter.Router
// contains filtered or unexported fields
}
HTTPMuxer is a wrapper around httprouter.Router. It intercepts all requests and reports useful information about them.
func (*HTTPMuxer) Endpoint ¶
func (m *HTTPMuxer) Endpoint(method, path string) HTTPEndpoint
Endpoint is used to define an HTTP endpoint. If you're not using the provided handlers, you can use this to time requests.
func (*HTTPMuxer) Handle ¶
func (m *HTTPMuxer) Handle(method, path string, handle httprouter.Handle)
Handle wraps the given Handle with stats reporting
func (*HTTPMuxer) HandlerFunc ¶
func (m *HTTPMuxer) HandlerFunc(method, path string, handler http.HandlerFunc)
HandlerFunc wraps the given HandlerFunc with stats reporting
type HTTPResp ¶
type HTTPResp struct {
http.ResponseWriter
// contains filtered or unexported fields
}
An HTTPResp wraps an http.ResponseWriter, providing timing and tracking support.
func (*HTTPResp) Free ¶
func (hr *HTTPResp) Free()
Free releases this object and puts it back into the pool. This is optional and may only be used when you're sure no one is hanging onto the *HTTPResp.
func (*HTTPResp) WriteHeader ¶
WriteHeader implements http.ResponseWriter.WriteHeader
type JSONFormat ¶
type JSONFormat struct {
Args struct {
// If the JSON should be pretty-printed
Pretty bool
}
}
JSONFormat formats snapshots as JSON
func (JSONFormat) FormatSnap ¶
func (j JSONFormat) FormatSnap(snap Snapshot) ([]byte, error)
FormatSnap implements Formatter.FormatSnap
func (JSONFormat) MimeType ¶
func (JSONFormat) MimeType() string
MimeType implements Formatter.MimeType
type LogstashFormat ¶
type LogstashFormat struct{}
LogstashFormat formats snapshots as JSON, ready for shipping to logstash
func (LogstashFormat) FormatSnap ¶
func (LogstashFormat) FormatSnap(snap Snapshot) ([]byte, error)
FormatSnap implements Formatter.FormatSnap
func (LogstashFormat) MimeType ¶
func (LogstashFormat) MimeType() string
MimeType implements Formatter.MimeType
type Name ¶
type Name struct {
// contains filtered or unexported fields
}
A Name is your ticket to naming a stat. Names are, by default, prefixed with the *S's prefix from whence they came. They may also be appended to to create new Names.
You should keep this around whenever you create a new Snapshotter since you'll need it to add the stat.
This is really just a wrapper for a string, but when used right, it forces proper path caching and discourages generating garbage.
type NewFormatter ¶
NewFormatter creates a new, configured Formatter.
type OutputConfig ¶
type OutputConfig struct {
Prod string // Which eio Producer to use
ProdArgs eio.Args // Args to pass to the sink
Fmt string // Name of formatter
FmtArgs eio.Args // Args to pass to the formatter
}
OutputConfig is used to configure outputs
type S ¶
type S struct {
// contains filtered or unexported fields
}
S is a stats aggregator.
func (*S) AddSnapshotter ¶
func (s *S) AddSnapshotter(name Name, snapper Snapshotter)
AddSnapshotter binds a snapshotter to this S.
func (*S) Name ¶
Name returns a new name, appended to this S's prefix. The given name is not escaped.
func (*S) Names ¶
Names returns a new Name with the given names joined with this S's prefix. The names are escaped individually.
func (*S) NewBoolGauge ¶
NewBoolGauge creates a bool gauge that's bound to this S
func (*S) NewCounter ¶
NewCounter creates a counter that's bound to this S
func (*S) NewFloatGauge ¶
func (s *S) NewFloatGauge(name string) *FloatGauge
NewFloatGauge creates a float gauge that's bound to this S
func (*S) NewHTTPMuxer ¶
NewHTTPMuxer creates a new HTTP muxer that exposes status information for all endpoints.
At /_status, information from the last snapshot is accessible with the given key (ie. GET "/_status?key=<key>").
func (*S) NewStringGauge ¶
func (s *S) NewStringGauge(name string) *StringGauge
NewStringGauge creates a string gauge that's bound to this S
type Snapshot ¶
type Snapshot []Stat
A Snapshot is a slice of stats sorted by name.
func (*Snapshot) Add ¶
Add a new value to this snapshot. Must be one of [bool, int64, float64, string].
func (*Snapshot) Take ¶
func (s *Snapshot) Take(name Name, sr Snapshotter)
Take takes a snapshot of a snapshotter
type Snapshotter ¶
type Snapshotter interface {
Snapshot(a Adder)
}
A Snapshotter takes a snapshot of itself, resets as necessary, and pushes the snapshotted value(s) to the given Adder.
type Stat ¶
type Stat struct {
// String here, not Name: once in a snapshot, name should already have
// been checked
Name string
Val interface{}
}
A Stat is a single stat value
type StringGauge ¶
type StringGauge struct {
// contains filtered or unexported fields
}
A StringGauge is a single string value that can be set at will
func (*StringGauge) Get ¶
func (g *StringGauge) Get() (v string)
Get gets the current value of the gauge
func (*StringGauge) Set ¶
func (g *StringGauge) Set(v string)
Set sets the current value of this gauge
func (*StringGauge) Snapshot ¶
func (g *StringGauge) Snapshot(a Adder)
Snapshot implements Snapshotter
type Timer ¶
type Timer struct {
// contains filtered or unexported fields
}
A Timer is used to time how long things take to run
func NewTimer ¶
NewTimer creates a new timer that outputs stats prefixed with the given name. The names are cached internally to limit allocations.
The timer also reports percentiles of data by sampling. The given `sampPercent` controls what percent of samples to save for percentile calculations (0 - 100).
Source Files