gostc

README

gostc

gostc is a Go StatsD/gost client.

Installation

go get github.com/cespare/gostc

Usage

Quick example:

client, err := gostc.NewClient("localhost:8125")
if err != nil {
  panic(err)
}

// Users will typically ignore the return errors of gostc methods as statsd
// is a best-effort service in most software.
client.Count("foobar", 1, 1)
client.Inc("foobar") // Same as above
t := time.Now()
time.Sleep(time.Second)
client.Time("blah", time.Since(t))

Documentation

Overview

Package gostc implemenents a StatsD/gost client.

This package performs minimal input validation, leaving that to the gost server.

Index

• Constants
• Variables
• type Client
  • func NewBufferedClient(addr string, queueSize int, maxPacketBytes int, flushDelay time.Duration) (*Client, error)
  • func NewClient(addr string) (*Client, error)
  • func NewDefaultBufferedClient(addr string) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) Count(key string, delta, samplingRate float64) error
  • func (c *Client) CountProb(key string, delta, p float64) error
  • func (c *Client) Gauge(key string, value float64) error
  • func (c *Client) Inc(key string) error
  • func (c *Client) IncProb(key string, p float64) error
  • func (c *Client) Set(key string, element []byte) error
  • func (c *Client) Time(key string, duration time.Duration) error
  • func (c *Client) WithNamespace(ns string) *Client

Constants

const (
	// DefaultQueueSize is the default value of queueSize for a buffered
	// client. With a value of 10000, if we assume 50 byte messages, then
	// we'll use 500KB of memory in the queue.
	DefaultQueueSize = 10000
	// DefaultMaxPacketBytes is the default value of maxPacketBytes for a
	// buffered client. 1000 is used because it is 1/10th of gost's default
	// max, and 1k packets seem to generally work for Linux local UDP.
	DefaultMaxPacketBytes = 1000
	// DefaultFlushDelay is the default value of flushDelay for a buffered
	// client.
	DefaultFlushDelay = time.Second
)

Variables

var ErrSamplingRate = errors.New("sampling rate must be in (0, 1]")

ErrSamplingRate is returned by client.Count (or variants) when a bad sampling rate value is provided.

Types

type Client

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

A Client is a StatsD/gost client which has a UDP connection.

func NewBufferedClient

func NewBufferedClient(addr string, queueSize int, maxPacketBytes int, flushDelay time.Duration) (*Client, error)

NewBufferedClient creates a client with the given UDP address that can buffer messages and sends them together in batches (separated by newlines, per the statsd protocol). Messages are formatted and sent to a single sending goroutine via a buffered channel. This has the effect of offloading the CPU and clock time of sending the messages from the calling goroutine, as well as possibly increasing efficiency by reducing the volume of UDP packets sent.

A buffered Client may or may not change (improve, degrade) performance in your particular scenario. Default to using a normal client (via NewClient) unless gostc performance is a measurable bottleneck, and then see if a buffered client helps (and keep measuring).

The three parameters queueSize, maxPacketBytes, and flushDelay tune the buffered channel size, maximum single packet size, and the flush delay. Messages are buffered until maxPacketBytes is reached or until flushDelay time has passed since the first message was buffered. Use NewDefaultBufferedClient for reasonable defaults.

Note that a buffered client cannot report UDP errors (it will silently fail).

func NewClient

func NewClient(addr string) (*Client, error)

NewClient creates a client with the given UDP address.

func NewDefaultBufferedClient

func NewDefaultBufferedClient(addr string) (*Client, error)

NewDefaultBufferedClient calls NewBufferedClient with tuning parameters queueSize, maxPacketBytes, and flashDelay set to DefaultQueueSize, DefaultMaxPacketBytes, and DefaultFlushDelay, respectively.

func (*Client) Close

func (c *Client) Close() error

Close closes the client's UDP connection. Afterwards, the client cannot be used. If the client is buffered, Close first sends any buffered messages.

func (*Client) Count

func (c *Client) Count(key string, delta, samplingRate float64) error

Count submits a statsd count message with the given key, value, and sampling rate.

func (*Client) CountProb

func (c *Client) CountProb(key string, delta, p float64) error

CountProb counts (key, delta) with probability p in (0, 1].

func (*Client) Gauge

func (c *Client) Gauge(key string, value float64) error

Gauge submits a statsd gauge message.

func (*Client) Inc

func (c *Client) Inc(key string) error

Inc submits a count with delta and sampling rate equal to 1.

func (*Client) IncProb

func (c *Client) IncProb(key string, p float64) error

IncProb increments key with probability p in (0, 1].

func (*Client) Set

func (c *Client) Set(key string, element []byte) error

Set submits a statsd set message.

func (*Client) Time

func (c *Client) Time(key string, duration time.Duration) error

Time submits a statsd timer message.

func (*Client) WithNamespace

func (c *Client) WithNamespace(ns string) *Client

WithNamespace creates a Client with a nested prefix that is automatically prepended to all messages. The new Client shares all its state with c (so it has the same configuration settings and only one needs to be closed). The namespace cannot be empty.