g2s

README

g2s

Get to Statsd: forward simple statistics to a statsd server.

Usage

g2s provides a Statsd object, which provides some convenience functions for each of the supported statsd statistic-types. Just call the relevant function on the Statsd object wherever it makes sense in your code.

s, err := g2s.Dial("udp", "statsd-server:8125")
if err != nil {
	// do something
}

s.Counter(1.0, "my.silly.counter", 1)
s.Timing(1.0, "my.silly.slow-process", time.Since(somethingBegan))
s.Timing(0.2, "my.silly.fast-process", 7*time.Millisecond)
s.Gauge(1.0, "my.silly.status", "green")

If you need to add a prefix to your metrics (for example, if you need to use an API key to send metrics to your statsd service) just use DialWithPrefix instead when instantiating your statsd struct:

s, err := g2s.DialWithPrefix("udp", "statsd-server:8125", "my-cool-prefix")
if err != nil {
	// do something
}

s.Counter(1.0, "this.gets.prefixed", 1)

If you use a standard UDP connection to a statsd server, all 'update'-class functions are goroutine safe. They should return quickly, but they're safe to fire in a seperate goroutine.

Upgrading API

Upgrade to the latest API by running ./fix.bash *.go where *.go expands to the paths of the source files you'd like to rewrite to the new API.

Documentation

Index

• type Statsd
  • func Dial(proto, endpoint string) (*Statsd, error)
  • func DialWithPrefix(proto, endpoint string, prefix string) (*Statsd, error)
  • func New(w io.Writer, prefix string) (*Statsd, error)
  • func (s *Statsd) Counter(sampleRate float32, bucket string, n ...int)
  • func (s *Statsd) Gauge(sampleRate float32, bucket string, v ...string)
  • func (s *Statsd) Timing(sampleRate float32, bucket string, d ...time.Duration)
• type Statter
  • func Noop() Statter

Types

type Statsd

type Statsd struct {
	// contains filtered or unexported fields
}

Statsd implements the Statter interface by writing StatsD formatted messages to the underlying writer.

func Dial

func Dial(proto, endpoint string) (*Statsd, error)

Dial takes the same parameters as net.Dial, ie. a transport protocol (typically "udp") and an endpoint. It returns a new Statsd structure, ready to use.

Note that g2s currently performs no management on the connection it creates.

func DialWithPrefix

func DialWithPrefix(proto, endpoint string, prefix string) (*Statsd, error)

Variant of Dial that accepts a prefix that will be prepended to the name of all buckets sent (so it can be used with services that require an API key)

func New

func New(w io.Writer, prefix string) (*Statsd, error)

New constructs a Statsd structure which will write statsd-protocol messages into the given io.Writer. New is intended to be used by consumers who want nonstandard behavior: for example, they may pass an io.Writer which performs buffering and aggregation of statsd-protocol messages.

Note that g2s provides no synchronization. If you pass an io.Writer which is not goroutine-safe, for example a bytes.Buffer, you must make sure you synchronize your calls to the Statter methods.

func (*Statsd) Counter

func (s *Statsd) Counter(sampleRate float32, bucket string, n ...int)

Counter sends one or more counter statistics to StatsD.

Application code should call it for every potential invocation of a statistic; it uses the sampleRate to determine whether or not to send or squelch the data, on an aggregate basis.

func (*Statsd) Gauge

func (s *Statsd) Gauge(sampleRate float32, bucket string, v ...string)

Gauge sends one or more gauge statistics to Statsd.

Application code should call it for every potential invocation of a statistic; it uses the sampleRate to determine whether or not to send or squelch the data, on an aggregate basis.

func (*Statsd) Timing

func (s *Statsd) Timing(sampleRate float32, bucket string, d ...time.Duration)

Timing sends one or more timing statistics to StatsD.

Application code should call it for every potential invocation of a statistic; it uses the sampleRate to determine whether or not to send or squelch the data, on an aggregate basis.

type Statter

type Statter interface {
	Counter(sampleRate float32, bucket string, n ...int)
	Timing(sampleRate float32, bucket string, d ...time.Duration)
	Gauge(sampleRate float32, bucket string, value ...string)
}

Statter collects the ways clients can send observations to a StatsD server.

func Noop

func Noop() Statter

Noop returns a struct that satisfies the Statter interface but silently ignores all Statter method invocations. It's designed to be used when normal g2s construction fails, eg.

s, err := g2s.Dial("udp", someEndpoint)
if err != nil {
    log.Printf("not sending statistics to statsd (%s)", err)
    s = g2s.Noop()
}