Build Status Code Coverage Documentation


statsd is a simple and efficient Statsd client.

See the benchmark for a comparison with other Go StatsD clients.


  • Supports all StatsD metrics: counter, gauge, timing and set
  • Supports InfluxDB and Datadog tags
  • Fast and GC-friendly: all functions for sending metrics do not allocate
  • Efficient: metrics are buffered by default
  • Simple and clean API
  • 100% test coverage
  • Versioned API using



go get


See the examples in the documentation.




Do you have any question the documentation does not answer? Is there a use case that you feel is common and is not well-addressed by the current API?

If so you are more than welcome to ask questions in the thread on golang-nuts or open an issue or send a pull-request here on Github.

Expand ▾ Collapse ▴



Package statsd is a simple and efficient StatsD client.


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().


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

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

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

StatsD homepage:





This section is empty.


This section is empty.


This section is empty.


type Client

type Client struct {
	// contains filtered or unexported fields

    A Client represents a StatsD client.

    func New

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

      New returns a new Client.

      func (*Client) Clone

      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.


        func (*Client) Close

        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

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

            Count adds n to bucket.

            func (*Client) Flush

            func (c *Client) Flush()

              Flush flushes the Client's buffer.

              func (*Client) Gauge

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

                Gauge records an absolute value for the given bucket.

                func (*Client) Histogram

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

                  Histogram sends an histogram value to a bucket.

                  func (*Client) Increment

                  func (c *Client) Increment(bucket string)

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

                    func (*Client) NewTiming

                    func (c *Client) NewTiming() Timing

                      NewTiming creates a new Timing.


                      func (*Client) Timing

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

                        Timing sends a timing value to a bucket.

                        func (*Client) Unique

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

                          Unique sends the given value to a set bucket.

                          type Option

                          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

                            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().


                              func ErrorHandler

                              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().


                                func FlushPeriod

                                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().


                                  func MaxPacketSize

                                  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().


                                    func Mute

                                    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.


                                      func Network

                                      func Network(network string) Option

                                        Network sets the network (udp, tcp, etc) used by the client. See the net.Dial documentation ( for the available network options.

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


                                        func Prefix

                                        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.


                                          func SampleRate

                                          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.


                                            func Tags

                                            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.


                                              func TagsFormat

                                              func TagsFormat(tf TagFormat) Option

                                                TagsFormat sets the format of tags.


                                                type TagFormat

                                                type TagFormat uint8

                                                  TagFormat represents the format of tags sent by a Client.

                                                  const (
                                                  	// InfluxDB tag format.
                                                  	// See
                                                  	InfluxDB TagFormat = iota + 1
                                                  	// Datadog tag format.
                                                  	// See

                                                  type Timing

                                                  type Timing struct {
                                                  	// contains filtered or unexported fields

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

                                                    func (Timing) Duration

                                                    func (t Timing) Duration() time.Duration

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

                                                      func (Timing) Send

                                                      func (t Timing) Send(bucket string)

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