README
¶
Gostats 
gostats is a Go metrics library with support for Counters, Gauges, and Timers.
Installation
go get github.com/lyft/gostats
Building & Testing
make install
make test
Usage
In order to start using gostats, import it into your project with:
import "github.com/lyft/gostats"
Mocking
A thread-safe mock sink is provided by the gostats/mock package. The mock sink also provides methods that are useful for testing (as demonstrated below).
package mock_test
import (
"testing"
"github.com/lyft/gostats"
"github.com/lyft/gostats/mock"
)
type Config struct {
Stats stats.Store
}
func TestMockExample(t *testing.T) {
sink := mock.NewSink()
conf := Config{
Stats: stats.NewStore(sink, false),
}
conf.Stats.NewCounter("name").Inc()
conf.Stats.Flush()
sink.AssertCounterEquals(t, "name", 1)
}
If you do not need to assert on the contents of the sink the below example can be used to quickly create a thread-safe stats.Scope:
package config
import (
"github.com/lyft/gostats"
"github.com/lyft/gostats/mock"
)
type Config struct {
Stats stats.Store
}
func NewConfig() *Config {
return &Config{
Stats: stats.NewDefaultStore(),
}
}
func NewMockConfig() *Config {
sink := mock.NewSink()
return &Config{
Stats: stats.NewStore(sink, false),
}
}
Documentation
¶
Overview ¶
Package stats is a statistics library created by Engineers at Lyft with support for Counters, Gauges, and Timers.
Index ¶
Constants ¶
const ( // DefaultUseStatsd use statsd as a stats sink, default is true. DefaultUseStatsd = true // DefaultStatsdHost is the default address where statsd is running at. DefaultStatsdHost = "localhost" // DefaultStatsdProtocol is TCP DefaultStatsdProtocol = "tcp" // DefaultStatsdPort is the default port where statsd is listening at. DefaultStatsdPort = 8125 // DefaultFlushIntervalS is the default flushing interval in seconds. DefaultFlushIntervalS = 5 // DefaultLoggingSinkDisabled is the default behavior of logging sink suppression, default is false. DefaultLoggingSinkDisabled = false )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Counter ¶
type Counter interface {
// Add increments the Counter by the argument's value.
Add(uint64)
// Inc increments the Counter by 1.
Inc()
// Set sets an internal counter value which will be written in the next flush.
// Its use is discouraged as it may break the counter's "always incrementing" semantics.
Set(uint64)
// String returns the current value of the Counter as a string.
String() string
// Value returns the current value of the Counter as a uint64.
Value() uint64
}
A Counter is an always incrementing stat.
type FlushableSink ¶ added in v0.2.12
type FlushableSink interface {
Sink
Flush()
}
FlushableSink is an extension of Sink that provides a Flush() function that will flush any buffered stats to the underlying store.
func NewLoggingSink ¶
func NewLoggingSink() FlushableSink
NewLoggingSink returns a Sink that flushes stats to os.StdErr.
func NewNetSink ¶ added in v0.3.10
func NewNetSink(opts ...SinkOption) FlushableSink
NewNetSink returns a FlushableSink that writes to a statsd sink over the network. By default settings are taken from the enviornment, but can be overridden via SinkOptions.
func NewNullSink ¶
func NewNullSink() FlushableSink
NewNullSink returns a Sink that does not have a backing store attached to it.
func NewTCPStatsdSink ¶ added in v0.2.0
func NewTCPStatsdSink(opts ...SinkOption) FlushableSink
NewTCPStatsdSink returns a new NetStink. This function name exists for backwards compatibility.
type Gauge ¶
type Gauge interface {
// Add increments the Gauge by the argument's value.
Add(uint64)
// Sub decrements the Gauge by the argument's value.
Sub(uint64)
// Inc increments the Gauge by 1.
Inc()
// Dec decrements the Gauge by 1.
Dec()
// Set sets the Gauge to a value.
Set(uint64)
// String returns the current value of the Gauge as a string.
String() string
// Value returns the current value of the Gauge as a uint64.
Value() uint64
}
A Gauge is a stat that can increment and decrement.
type MockSink ¶ added in v0.2.0
type MockSink struct {
Counters map[string]uint64
Timers map[string]uint64
Gauges map[string]uint64
// contains filtered or unexported fields
}
MockSink describes an in-memory Sink used for testing.
DEPRECATED: use "github.com/lyft/gostats/mock" instead.
func NewMockSink ¶
func NewMockSink() (m *MockSink)
NewMockSink returns a MockSink that flushes stats to in-memory maps. An instance of MockSink is not safe for concurrent use.
DEPRECATED: use "github.com/lyft/gostats/mock" instead.
func (*MockSink) FlushCounter ¶ added in v0.2.0
FlushCounter satisfies the Sink interface.
func (*MockSink) FlushGauge ¶ added in v0.2.0
FlushGauge satisfies the Sink interface.
func (*MockSink) FlushTimer ¶ added in v0.2.0
FlushTimer satisfies the Sink interface.
type Scope ¶
type Scope interface {
// Scope creates a subscope.
Scope(name string) Scope
// ScopeWithTags creates a subscope with Tags to a store or scope. All child scopes and metrics
// will inherit these tags by default.
ScopeWithTags(name string, tags map[string]string) Scope
// Store returns the Scope's backing Store.
Store() Store
// NewCounter adds a Counter to a store, or a scope.
NewCounter(name string) Counter
// NewCounterWithTags adds a Counter with Tags to a store, or a scope.
NewCounterWithTags(name string, tags map[string]string) Counter
// NewPerInstanceCounter adds a Per instance Counter with optional Tags to a store, or a scope.
NewPerInstanceCounter(name string, tags map[string]string) Counter
// NewGauge adds a Gauge to a store, or a scope.
NewGauge(name string) Gauge
// NewGaugeWithTags adds a Gauge with Tags to a store, or a scope.
NewGaugeWithTags(name string, tags map[string]string) Gauge
// NewPerInstanceGauge adds a Per instance Gauge with optional Tags to a store, or a scope.
NewPerInstanceGauge(name string, tags map[string]string) Gauge
// NewTimer adds a Timer to a store, or a scope.
NewTimer(name string) Timer
// NewTimerWithTags adds a Timer with Tags to a store, or a scope with Tags.
NewTimerWithTags(name string, tags map[string]string) Timer
// NewPerInstanceTimer adds a Per instance Timer with optional Tags to a store, or a scope.
NewPerInstanceTimer(name string, tags map[string]string) Timer
}
A Scope namespaces Statistics.
store := stats.NewDefaultStore()
scope := stats.Scope("service")
// the following counter will be emitted at the stats tree rooted at `service`.
c := scope.NewCounter("success")
Additionally you can create subscopes:
store := stats.NewDefaultStore()
scope := stats.Scope("service")
networkScope := scope.Scope("network")
// the following counter will be emitted at the stats tree rooted at service.network.
c := networkScope.NewCounter("requests")
type Settings ¶
type Settings struct {
// Use statsd as a stats sink.
UseStatsd bool `envconfig:"USE_STATSD" default:"true"`
// Address where statsd is running at.
StatsdHost string `envconfig:"STATSD_HOST" default:"localhost"`
// Network protocol used to connect to statsd
StatsdProtocol string `envconfig:"STATSD_PROTOCOL" default:"tcp"`
// Port where statsd is listening at.
StatsdPort int `envconfig:"STATSD_PORT" default:"8125"`
// Flushing interval.
FlushIntervalS int `envconfig:"GOSTATS_FLUSH_INTERVAL_SECONDS" default:"5"`
// Disable the LoggingSink when USE_STATSD is false and use the NullSink instead.
// This will cause all stats to be silently dropped.
LoggingSinkDisabled bool `envconfig:"GOSTATS_LOGGING_SINK_DISABLED" default:"false"`
}
The Settings type is used to configure gostats. gostats uses environment variables to setup its settings.
func GetSettings ¶
func GetSettings() Settings
GetSettings returns the Settings gostats will run with.
type Sink ¶
type Sink interface {
FlushCounter(name string, value uint64)
FlushGauge(name string, value uint64)
FlushTimer(name string, value float64)
}
A Sink is used by a Store to flush its data. These functions may buffer the given data.
type SinkOption ¶ added in v0.3.9
type SinkOption interface {
// contains filtered or unexported methods
}
An SinkOption configures a Sink.
func WithLogger ¶ added in v0.3.9
func WithLogger(log *logger.Logger) SinkOption
WithLogger configures the sink to use the provided logger otherwise the standard logrus logger is used.
func WithStatsdHost ¶ added in v0.3.9
func WithStatsdHost(host string) SinkOption
WithStatsdHost sets the host of the statsd sink otherwise the host is read from the environment variable "STATSD_HOST".
func WithStatsdPort ¶ added in v0.3.9
func WithStatsdPort(port int) SinkOption
WithStatsdPort sets the port of the statsd sink otherwise the port is read from the environment variable "STATSD_PORT".
func WithStatsdProtocol ¶ added in v0.3.10
func WithStatsdProtocol(protocol string) SinkOption
WithStatsdProtocol sets the network protocol ("udp" or "tcp") of the statsd sink otherwise the protocol is read from the environment variable "STATSD_PROTOCOL".
type StatGenerator ¶
type StatGenerator interface {
// Runs the StatGenerator to generate Stats.
GenerateStats()
}
A StatGenerator can be used to programatically generate stats. StatGenerators are added to a store via
AddStatGenerator(StatGenerator)
An example is https://github.com/lyft/gostats/blob/master/runtime.go.
func NewRuntimeStats ¶
func NewRuntimeStats(scope Scope) StatGenerator
NewRuntimeStats returns a StatGenerator with common Go runtime stats like memory allocated, total mallocs, total frees, etc.
type Store ¶
type Store interface {
// Flush Counters and Gauges to the Sink attached to the Store.
// To flush the store at a regular interval call the
// Start(*time.Ticker)
// method on it.
//
// The store will flush either at the regular interval, or whenever
// Flush()
// is called. Whenever the store is flushed,
// the store will call
// GenerateStats()
// on all of its stat generators,
// and flush all the Counters and Gauges registered with it.
Flush()
// Start a timer for periodic stat Flushes.
Start(*time.Ticker)
// Add a StatGenerator to the Store that programatically generates stats.
AddStatGenerator(StatGenerator)
Scope
}
A Store holds statistics. There are two options when creating a new store:
create a store backed by a tcp_sink to statsd s := stats.NewDefaultStore() create a store with a user provided Sink s := stats.NewStore(sink, true)
Currently that only backing store supported is statsd via a TCP sink, https://github.com/lyft/gostats/blob/master/tcp_sink.go. However, implementing other Sinks (https://github.com/lyft/gostats/blob/master/sink.go) should be simple.
A store holds Counters, Gauges, and Timers. You can add unscoped Counters, Gauges, and Timers to the store with:
s := stats.NewDefaultStore()
c := s.New[Counter|Gauge|Timer]("name")
func NewDefaultStore ¶
func NewDefaultStore() Store
NewDefaultStore returns a Store with a TCP statsd sink, and a running flush timer.
type Timer ¶
type Timer interface {
// AddValue flushs the timer with the argument's value.
AddValue(float64)
// AllocateSpan allocates a Timespan.
AllocateSpan() Timespan
}
A Timer is used to flush timing statistics.
type Timespan ¶
type Timespan interface {
// End the Timespan and flush it.
Complete() time.Duration
// End the Timespan and flush it. Adds additional time.Duration to the measured time
CompleteWithDuration(time.Duration)
}
A Timespan is used to measure spans of time. They measure time from the time they are allocated by a Timer with
AllocateSpan()
until they call
Complete()
or
CompleteWithDuration(time.Duration)
When either function is called the timespan is flushed. When Complete is called the timespan is flushed.
A Timespan can be flushed at function return by calling Complete with golang's defer statement.
Source Files
Directories