statsd.v2: gopkg.in/alexcesaro/statsd.v2 Index | Examples | Files

package statsd

import "gopkg.in/alexcesaro/statsd.v2"

Package statsd is a simple and efficient StatsD client.

Options

Use options to configure the Client: target host/port, sampling rate, tags, etc.

Whenever you want to use different options (e.g. other tags, different sampling rate), you should use the Clone() method of the Client.

Because when cloning a Client, the same connection is reused so this is way cheaper and more efficient than creating another Client using New().

Internals

Client's methods buffer metrics. The buffer is flushed when either: 

- the background goroutine flushes the buffer (every 100ms by default)
- the buffer is full (1440 bytes by default so that IP packets are not
  fragmented)

The background goroutine can be disabled using the FlushPeriod(0) option.

Buffering can be disabled using the MaxPacketSize(0) option.

StatsD homepage: https://github.com/etsy/statsd

Example

Code: 

c, err := statsd.New() // Connect to the UDP port 8125 by default.
if err != nil {
    // If nothing is listening on the target port, an error is returned and
    // the returned client does nothing but is still usable. So we can
    // just log the error and go on.
    log.Print(err)
}
defer c.Close()

// Increment a counter.
c.Increment("foo.counter")

// Gauge something.
c.Gauge("num_goroutine", runtime.NumGoroutine())

// Time something.
t := c.NewTiming()
ping("http://example.com/")
t.Send("homepage.response_time")

// It can also be used as a one-liner to easily time a function.
pingHomepage := func() {
    defer c.NewTiming().Send("homepage.response_time")

    ping("http://example.com/")
}
pingHomepage()

// Cloning a Client allows using different parameters while still using the
// same connection.
// This is way cheaper and more efficient than using New().
stat := c.Clone(statsd.Prefix("http"), statsd.SampleRate(0.2))
stat.Increment("view") // Increments http.view

Index

Examples

Package Files

conn.go doc.go options.go statsd.go

type Client Uses

❖
type Client struct {
    // contains filtered or unexported fields
}

A Client represents a StatsD client.

func New Uses

❖
func New(opts ...Option) (*Client, error)

New returns a new Client.

func (*Client) Clone Uses

❖
func (c *Client) Clone(opts ...Option) *Client

Clone returns a clone of the Client. The cloned Client inherits its configuration from its parent.

All cloned Clients share the same connection, so cloning a Client is a cheap operation.

Example

Code: 

c, err := statsd.New(statsd.Prefix("my_app"))
if err != nil {
    log.Print(err)
}

httpStats := c.Clone(statsd.Prefix("http"))
httpStats.Increment("foo.bar") // Increments: my_app.http.foo.bar

func (*Client) Close Uses

❖
func (c *Client) Close()

Close flushes the Client's buffer and releases the associated ressources. The Client and all the cloned Clients must not be used afterward.

func (*Client) Count Uses

❖
func (c *Client) Count(bucket string, n interface{})

Count adds n to bucket.

func (*Client) Flush Uses

❖
func (c *Client) Flush()

Flush flushes the Client's buffer.

func (*Client) Gauge Uses

❖
func (c *Client) Gauge(bucket string, value interface{})

Gauge records an absolute value for the given bucket.

func (*Client) Histogram Uses

❖
func (c *Client) Histogram(bucket string, value interface{})

Histogram sends an histogram value to a bucket.

func (*Client) Increment Uses

❖
func (c *Client) Increment(bucket string)

Increment increment the given bucket. It is equivalent to Count(bucket, 1).

func (*Client) NewTiming Uses

❖
func (c *Client) NewTiming() Timing

NewTiming creates a new Timing.

Example

Code: 

// Send a timing metric each time the function is run.
defer c.NewTiming().Send("homepage.response_time")
ping("http://example.com/")

func (*Client) Timing Uses

❖
func (c *Client) Timing(bucket string, value interface{})

Timing sends a timing value to a bucket.

func (*Client) Unique Uses

❖
func (c *Client) Unique(bucket string, value string)

Unique sends the given value to a set bucket.

type Option Uses

❖
type Option func(*config)

An Option represents an option for a Client. It must be used as an argument to New() or Client.Clone().

func Address Uses

❖
func Address(addr string) Option

Address sets the address of the StatsD daemon.

By default, ":8125" is used. This option is ignored in Client.Clone().

Example

Code: 

c, err = statsd.New(statsd.Address("192.168.0.5:8126"))

func ErrorHandler Uses

❖
func ErrorHandler(h func(error)) Option

ErrorHandler sets the function called when an error happens when sending metrics (e.g. the StatsD daemon is not listening anymore).

By default, these errors are ignored. This option is ignored in Client.Clone().

Example

Code: 

c, err = statsd.New(statsd.ErrorHandler(func(err error) {
    log.Print(err)
}))

func FlushPeriod Uses

❖
func FlushPeriod(p time.Duration) Option

FlushPeriod sets how often the Client's buffer is flushed. If p is 0, the goroutine that periodically flush the buffer is not lauched and the buffer is only flushed when it is full.

By default, the flush period is 100 ms. This option is ignored in Client.Clone().

Example

Code: 

c, err = statsd.New(statsd.FlushPeriod(10 * time.Millisecond))

func MaxPacketSize Uses

❖
func MaxPacketSize(n int) Option

MaxPacketSize sets the maximum packet size in bytes sent by the Client.

By default, it is 1440 to avoid IP fragmentation. This option is ignored in Client.Clone().

Example

Code: 

c, err = statsd.New(statsd.MaxPacketSize(512))

func Mute Uses

❖
func Mute(b bool) Option

Mute sets whether the Client is muted. All methods of a muted Client do nothing and return immedialtly.

This option can be used in Client.Clone() only if the parent Client is not muted. The clones of a muted Client are always muted.

Example

Code: 

c, err := statsd.New(statsd.Mute(true))
if err != nil {
    log.Print(err)
}
c.Increment("foo.bar") // Does nothing.

func Network Uses

❖
func Network(network string) Option

Network sets the network (udp, tcp, etc) used by the client. See the net.Dial documentation (https://golang.org/pkg/net/#Dial) for the available network options.

By default, network is udp. This option is ignored in Client.Clone().

Example

Code: 

// Send metrics using a TCP connection.
c, err = statsd.New(statsd.Network("tcp"))

func Prefix Uses

❖
func Prefix(p string) Option

Prefix appends the prefix that will be used in every bucket name.

Note that when used in cloned, the prefix of the parent Client is not replaced but is prepended to the given prefix.

Example

Code: 

c, err := statsd.New(statsd.Prefix("my_app"))
if err != nil {
    log.Print(err)
}
c.Increment("foo.bar") // Increments: my_app.foo.bar

func SampleRate Uses

❖
func SampleRate(rate float32) Option

SampleRate sets the sample rate of the Client. It allows sending the metrics less often which can be useful for performance intensive code paths.

Example

Code: 

c, err = statsd.New(statsd.SampleRate(0.2)) // Send metrics 20% of the time.

func Tags Uses

❖
func Tags(tags ...string) Option

Tags appends the given tags to the tags sent with every metrics. If a tag already exists, it is replaced.

The tags must be set as key-value pairs. If the number of tags is not even, Tags panics.

If the format of tags have not been set using the TagsFormat option, the tags will be ignored.

Example

Code: 

c, err = statsd.New(
    statsd.TagsFormat(statsd.InfluxDB),
    statsd.Tags("region", "us", "app", "my_app"),
)

func TagsFormat Uses

❖
func TagsFormat(tf TagFormat) Option

TagsFormat sets the format of tags.

Example

Code: 

c, err = statsd.New(statsd.TagsFormat(statsd.InfluxDB))

type TagFormat Uses

❖
type TagFormat uint8

TagFormat represents the format of tags sent by a Client.

❖
const (
    // InfluxDB tag format.
    // See https://influxdb.com/blog/2015/11/03/getting_started_with_influx_statsd.html
    InfluxDB TagFormat = iota + 1
    // Datadog tag format.
    // See http://docs.datadoghq.com/guides/metrics/#tags
    Datadog
)

type Timing Uses

❖
type Timing struct {
    // contains filtered or unexported fields
}

A Timing is an helper object that eases sending timing values.

func (Timing) Duration Uses

❖
func (t Timing) Duration() time.Duration

Duration returns the time elapsed since the creation of the Timing.

func (Timing) Send Uses

❖
func (t Timing) Send(bucket string)

Send sends the time elapsed since the creation of the Timing.

Package statsd imports 8 packages (graph) and is imported by 75 packages. Updated 2020-05-24. Refresh now. Tools for package owners.