README
¶
stats
package to capture vital statistics about a golang process.
allows other packages to just import the package and start publishing stats similar to how the github.com/deep-compute/log is imported and used (global context).
Usage
Basic Usage
The main program needs to inform the package about the statsd address and any prefixes to apply. Make sure to call Init ! it does some other stuff like tracking runtime gc / proc stats etc . It also makes all calls no-op when you want to disable stats generation.
package main
import (
"github.com/deep-compute/stats"
"github.com/random/randompackage"
)
func main() {
stats.SetAddress("localhost:8125")
// if the host machine has host name node0-mac-pc
// we want it to be node0-mac-pc.exampleprog0.<rest of stats>
stats.SetHostnamedPrefix("exampleprog0")
if e := stats.Init(); e != nil {
panic(e)
}
randompackage.RandomFunc()
// more documentation eventually
}
The package needs to just import and publish stats
package randompackage
import (
"fmt"
"github.com/deep-compute/stats"
)
func RandomFunc() {
// does not care about the prefix
// but assume the main program above was used,
// this results in node0-mac-pc.exampleprog0.randomfunc
stats.Incr("randomfunc", 1)
fmt.Printf("Hello World!")
}
Disabling statsd for some programs
The stats package looks for an environmental variable DC_STATSD_DISABLE.
DC_STATSD_DISABLE=1 go run main.go
// or export it
export DC_STATSD_DISABLE=1
go run main.go
unset DC_STATSD_DISABLE
Locker stats
The stats package also has two Locker objects Mutex and RWMutex. They capture stats about how much time was spent waiting to acquire lock. As a future update, it also captures how much time the lock was enabled for.
Documentation
¶
Overview ¶
stats package provides a mechanism to capture vital statistics and transmit to a StatsD server
Index ¶
- Constants
- Variables
- func DisableGlobalStats()
- func GetDefaultPrefix() string
- func Init() error
- func IsDisabled() bool
- func IsEnabled() bool
- func SubmitBulk(bstats *BulkStats)
- type BulkStats
- type Locker
- type Mutex
- type RWLocker
- type RWMutex
- type Stats
- func (p *Stats) Absolute(stat string, value int64) error
- func (p *Stats) Decr(stat string, count int64) error
- func (p *Stats) FAbsolute(stat string, value float64) error
- func (p *Stats) FGauge(stat string, value float64) error
- func (p *Stats) FGaugeDelta(stat string, value float64) error
- func (p *Stats) Gauge(stat string, value int64) error
- func (p *Stats) GaugeDelta(stat string, value int64) error
- func (p *Stats) Incr(stat string, count int64) error
- func (p *Stats) Init() error
- func (p *Stats) NewMutex(prefix string) *Mutex
- func (p *Stats) NewRWMutex(prefix string) *RWMutex
- func (p *Stats) PrecisionTiming(stat string, delta time.Duration) error
- func (p *Stats) SetAddress(address string) *Stats
- func (p *Stats) SetHostnamedPrefix(prefix string) *Stats
- func (p *Stats) SetPrefix(prefix string) *Stats
- func (p *Stats) SubmitBulk(bstats *BulkStats)
- func (p *Stats) Timing(stat string, delta int64) error
- func (p *Stats) TimingSince(stat string, st time.Time) error
- func (p *Stats) Total(stat string, value int64) error
Constants ¶
const DISABLE_STATS = "DC_STATSD_DISABLE"
Variables ¶
var Absolute = func(stat string, value int64) error {
return stats.Absolute(stat, value)
}
var DEFAULT_FLUSH_INTERVAL time.Duration = 1 * time.Second
var DEFAULT_PROC_STATS_INTERVAL time.Duration = 1 * time.Second
var DEFAULT_RUNTIME_STATS_INTERVAL time.Duration = 1 * time.Second
var Decr = func(stat string, count int64) error {
return stats.Decr(stat, count)
}
var FAbsolute = func(stat string, value float64) error {
return stats.FAbsolute(stat, value)
}
var FGauge = func(stat string, value float64) error {
return stats.FGauge(stat, value)
}
var FGaugeDelta = func(stat string, value float64) error {
return stats.FGaugeDelta(stat, value)
}
var Gauge = func(stat string, value int64) error {
return stats.Gauge(stat, value)
}
var GaugeDelta = func(stat string, value int64) error {
return stats.GaugeDelta(stat, value)
}
var Incr = func(stat string, count int64) error {
return stats.Incr(stat, count)
}
var NewMutex = func(prefix string) Locker { if prefix != "" { prefix = fmt.Sprintf("mutex.%s", prefix) } return stats.NewMutex(prefix) }
var NewRWMutex = func(prefix string) RWLocker { if prefix != "" { prefix = fmt.Sprintf("rwmutex.%s", prefix) } return stats.NewRWMutex(prefix) }
var Noop = func(i, j interface{}) error { return nil }
var NoopFloat = func(key string, value float64) error { return nil }
var NoopInt = func(key string, value int64) error { return nil }
var NoopMutex = func(prefix string) Locker { return &sync.Mutex{} }
var NoopRWMutex = func(prefix string) RWLocker { return &sync.RWMutex{} }
var PrecisionTiming = func(stat string, delta time.Duration) error {
return stats.PrecisionTiming(stat, delta)
}
var Timing = func(stat string, delta int64) error {
return stats.Timing(stat, delta)
}
var TimingSince = func(stat string, st time.Time) error {
return stats.TimingSince(stat, st)
}
var Total = func(stat string, value int64) error {
return stats.Total(stat, value)
}
Functions ¶
func DisableGlobalStats ¶
func DisableGlobalStats()
DisableGlobalStats allows the user to disable all global level stats One may still create stats objects and use them - this is just for all the ones that rely on global level stats
func GetDefaultPrefix ¶
func GetDefaultPrefix() string
GetDefaultPrefix generates Stats prefix based on the hostname and the current process name in the format "<host>.<process>."
func Init ¶
func Init() error
Init is called once all configurations have been set
e.g. stats.SetHostnamedPrefix
if e := stats.Init(); e != nil {
panic(e)
}
func IsDisabled ¶
func IsDisabled() bool
IsDisabled checks if stats are disabled i.e. if DISABLE_STATS has been set one can set it by `export DC_STATSD_DISABLE=1` or any other value other than ""
func IsEnabled ¶
func IsEnabled() bool
IsEnabled checks if stats should be enabled i.e. DISABLE_STATS is not set one can unset it using `unset DC_STATSD_DISABLE`
func SubmitBulk ¶
func SubmitBulk(bstats *BulkStats)
Types ¶
type BulkStats ¶
type BulkStats struct {
Timing map[string]int64 `json:"timing"`
Gauge map[string]int64 `json:"gauge"`
Incr map[string]int64 `json:"incr"`
Decr map[string]int64 `json:"decr"`
}
BulkStats represents a set of collected measurements which need to be submitted to the StatsServer. This abstraction is useful when stats are collected from a process that does not have direct access to the StatsD server TODO: Only a few types are supported. Need to support all.
type Mutex ¶
type Mutex struct {
// the stats object. if nil, then global stats is used
Stats *Stats
// prefix to be used for the metric representing locking time
Prefix string
// the actual mutex
sync.Mutex
}
Mutex has the same behavior as sync.Mutex. In addition, it supports
measuring the amount time a thread is blocked waiting to acquire the mutex and then submitting the same to stats
TODO add an unlock that lets us calculate the time a lock is used for.
type RWMutex ¶
type RWMutex struct {
// the stats object. if nil, then global stats is used
Stats *Stats
// prefix to be used for the metric representing locking time
Prefix string
// the actual mutex
sync.RWMutex
}
RWMutex has the same behavior as sync.RWMutex. In addition, it supports
measuring the amount time a thread is blocked waiting to acquire the mutex and then submitting the same to stats
type Stats ¶
type Stats struct {
// Duration of time after which the buffered stats must be flushed
// to the StatsD server periodically
FlushInterval time.Duration
// Duration of time after which various runtime stats about the current
// process are collected and submitted periodically
RuntimeStatsInterval time.Duration
// Duration of time after which stats from /proc for the current process
// are collected and submitted periodically
ProcStatsInterval time.Duration
// The ip:port of the StatsD server (port is optional). If empty then
// localhost and default port are assumed.
Address string
// Prefix used for each stats key in order to achieve namespacing in the
// stats hierarchy
Prefix string
// contains filtered or unexported fields
}
Stats represents the abstraction that helps in collecting stats from a process. All stats submitted to it are buffered locally for performance and then flushed to the StatsD server periodically.
func SetAddress ¶
func SetHostnamedPrefix ¶
func (*Stats) NewMutex ¶
NewMutex creates a new mutex (type stats.Mutex)
the @prefix is used to record lock time stats with stats server
func (*Stats) NewRWMutex ¶
NewRWMutex creates a new mutex (type stats.RWMutex)
the @prefix is used to record lock time stats with stats server
func (*Stats) PrecisionTiming ¶
func (*Stats) SetAddress ¶
SetAddress accepts an address to StatsD server of the format ip:port (port is optional. default assumed if not present). if ip is not provided then localhost is assumed. New address is set and the connection is restarted
func (*Stats) SetHostnamedPrefix ¶
SetHostnamedPrefix sets a new prefix which is of the format <hostname>.<@prefix> and restarts connection
Source Files