statsd

README

statsd

Statsd Go client library

This project has been originally forked and extended from https://github.com/alexcesaro/statsd

This package is a simple and efficient StatsD client. StatsD is a network daemon that listens for statistics and aggregates them to one or more pluggable backend services (e.g., Graphite). For more information about StatsD, visit the StatsD homepage: https://github.com/etsy/statsd

The packages documentation is available at: https://pkg.go.dev/github.com/tecnickcom/statsd

• category Library
• license MIT
• link https://github.com/tecnickcom/statsd

---

Features

• 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

---

Developers' Quick Start

To quickly get started with this project, follow these steps:

1. Ensure you have installed the latest Go version.
2. Clone the repository: git clone https://github.com/tecnickcom/statsd.git.
3. Change into the project directory: cd statsd.
4. Install the required dependencies and test everything: DEVMODE=LOCAL make x.

Now you are ready to start developing with statsd!

This project includes a Makefile that allows you to test and build the project in a Linux-compatible system with simple commands.
All the artifacts and reports produced using this Makefile are stored in the target folder.

Alternatively, everything can be built inside a Docker container using the command make dbuild that uses the environment defined at resources/docker/Dockerfile.dev.

To see all available options:

make help

---

Running all tests

Before committing the code, please format it and check if it passes all tests using

DEVMODE=LOCAL make x

---

Example

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

Documentation

Overview

Package statsd is a simple and efficient StatsD client.

StatsD is a network daemon that listens for statistics and aggregates them to one or more pluggable backend services (e.g., Graphite).

The statsd package provides options to configure the client, such as the target host/port, sampling rate, and tags. To use different options, you can clone the client using the Clone() method.

The client's methods buffer metrics, and the buffer is flushed either by the background goroutine (every 100ms by default) or when the buffer is full (1440 bytes by default to avoid IP packet fragmentation). You can disable the background goroutine using the FlushPeriod(0) option and disable buffering using the MaxPacketSize(0) option.

For more information about StatsD, visit the StatsD homepage: https://github.com/etsy/statsd

Example

package main

import (
	"log"
	"runtime"

	"github.com/tecnickcom/statsd"
)

func ping(_ string) {}

func main() {
	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

• type Client
  • func New(opts ...Option) (*Client, error)
  • func (c *Client) Clone(opts ...Option) *Client
  • func (c *Client) Close()
  • func (c *Client) Count(bucket string, n interface{})
  • func (c *Client) Flush()
  • func (c *Client) Gauge(bucket string, value interface{})
  • func (c *Client) Histogram(bucket string, value interface{})
  • func (c *Client) Increment(bucket string)
  • func (c *Client) NewTiming() Timing
  • func (c *Client) Timing(bucket string, value interface{})
  • func (c *Client) Unique(bucket string, value string)
• type Option
  • func Address(addr string) Option
  • func ErrorHandler(h func(error)) Option
  • func FlushPeriod(p time.Duration) Option
  • func MaxPacketSize(n int) Option
  • func Mute(b bool) Option
  • func Network(network string) Option
  • func Prefix(p string) Option
  • func SampleRate(rate float32) Option
  • func Tags(tags ...string) Option
  • func TagsFormat(tf TagFormat) Option
• type TagFormat
• type Timing
  • func (t Timing) Duration() time.Duration
  • func (t Timing) Send(bucket string)

Examples

• Package
• Address
• Client.Clone
• Client.NewTiming
• ErrorHandler
• FlushPeriod
• MaxPacketSize
• Mute
• Network
• Prefix
• SampleRate
• Tags
• TagsFormat

Types

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.

Example

package main

import (
	"log"

	"github.com/tecnickcom/statsd"
)

func main() {
	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

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.

Example

package main

import (
	"log"

	"github.com/tecnickcom/statsd"
)

func ping(_ string) {}

func main() {
	c, err := statsd.New()
	if err != nil {
		log.Print(err)
	}

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

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

Example

package main

import (
	"log"

	"github.com/tecnickcom/statsd"
)

func main() {
	_, err := statsd.New(statsd.Address("192.168.0.5:8126"))
	if err != nil {
		log.Print(err)
	}
}

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

Example

package main

import (
	"log"

	"github.com/tecnickcom/statsd"
)

func main() {
	_, err := statsd.New(statsd.ErrorHandler(func(err error) {
		log.Print(err)
	}))
	if err != nil {
		log.Print(err)
	}
}

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

Example

package main

import (
	"log"
	"time"

	"github.com/tecnickcom/statsd"
)

func main() {
	_, err := statsd.New(statsd.FlushPeriod(10 * time.Millisecond))
	if err != nil {
		log.Print(err)
	}
}

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

Example

package main

import (
	"log"

	"github.com/tecnickcom/statsd"
)

func main() {
	_, err := statsd.New(statsd.MaxPacketSize(512))
	if err != nil {
		log.Print(err)
	}
}

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.

Example

package main

import (
	"log"

	"github.com/tecnickcom/statsd"
)

func main() {
	c, err := statsd.New(statsd.Mute(true))
	if err != nil {
		log.Print(err)
	}

	c.Increment("foo.bar") // Does nothing.
}

func Network

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

package main

import (
	"log"

	"github.com/tecnickcom/statsd"
)

func main() {
	// Send metrics using a TCP connection.
	_, err := statsd.New(statsd.Network("tcp"))
	if err != nil {
		log.Print(err)
	}
}

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.

Example

package main

import (
	"log"

	"github.com/tecnickcom/statsd"
)

func main() {
	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

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

package main

import (
	"log"

	"github.com/tecnickcom/statsd"
)

func main() {
	_, err := statsd.New(statsd.SampleRate(0.2)) // Send metrics 20% of the time.
	if err != nil {
		log.Print(err)
	}
}

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.

Example

package main

import (
	"log"

	"github.com/tecnickcom/statsd"
)

func main() {
	_, err := statsd.New(
		statsd.TagsFormat(statsd.InfluxDB),
		statsd.Tags("region", "us", "app", "my_app"),
	)
	if err != nil {
		log.Print(err)
	}
}

func TagsFormat

func TagsFormat(tf TagFormat) Option

TagsFormat sets the format of tags.

Example

package main

import (
	"log"

	"github.com/tecnickcom/statsd"
)

func main() {
	_, err := statsd.New(statsd.TagsFormat(statsd.InfluxDB))
	if err != nil {
		log.Print(err)
	}
}

type TagFormat

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

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.