statsd

Documentation

Overview

Package statsd implements a client and a debugging server for UDP statsd datagrams.

Index

• Constants
• func IsErrUseOfClosedNetworkConnection(err error) bool
• func NewUDPListener(addr string) (net.PacketConn, error)
• func NewUnixgramListener(path string) (net.PacketConn, error)
• func Tag(k, v string) string
• type Client
  • func New(opts ...ClientOpt) (*Client, error)
  • func (c *Client) AddDefaultTag(name, value string)
  • func (c *Client) AddDefaultTags(tags ...string)
  • func (c *Client) Close() error
  • func (c *Client) Count(name string, value int64, tags ...string) error
  • func (c *Client) DefaultTags() []string
  • func (c *Client) Distribution(name string, value float64, tags ...string) error
  • func (c *Client) Flush() error
  • func (c *Client) Gauge(name string, value float64, tags ...string) error
  • func (c *Client) Histogram(name string, value float64, tags ...string) error
  • func (c *Client) Increment(name string, tags ...string) error
  • func (c *Client) TimeInMilliseconds(name string, value time.Duration, tags ...string) error
• type ClientOpt
  • func OptAddr(addr string) ClientOpt
  • func OptConfig(cfg Config) ClientOpt
  • func OptDialTimeout(timeout time.Duration) ClientOpt
  • func OptMaxBufferSize(count int) ClientOpt
  • func OptMaxPacketSize(sizeBytes int) ClientOpt
  • func OptSampleRate(rate float64) ClientOpt
• type Config
  • func (c Config) IsZero() bool
  • func (c *Config) Resolve(ctx context.Context) error
• type Metric
  • func (m Metric) Duration() (time.Duration, error)
  • func (m Metric) Float64() (float64, error)
  • func (m Metric) Int64() (int64, error)
• type Server
  • func (s *Server) MaxPacketSizeOrDefault() int
  • func (s *Server) Start() error
  • func (s *Server) Stop() error

Constants

const (
	ErrAddrUnset         ex.Class = "statsd client address unset"
	ErrMaxPacketSize     ex.Class = "statsd max packet size exceeded"
	ErrSampleRateInvalid ex.Class = "statsd invalid sample rate"
)

Error classes.

const (
	DefaultDialTimeout   = time.Second
	DefaultMaxPacketSize = 1 << 12 // 2^12 or 4kB
	DefaultMaxBufferSize = 32
)

Constants

const (
	MetricTypeCount        = "c"
	MetricTypeGauge        = "g"
	MetricTypeHistogram    = "h"
	MetricTypeDistribution = "d"
	MetricTypeTimer        = "ms"
)

MetricTypes

Functions

func IsErrUseOfClosedNetworkConnection

func IsErrUseOfClosedNetworkConnection(err error) bool

IsErrUseOfClosedNetworkConnection is an error class checker.

func NewUDPListener

func NewUDPListener(addr string) (net.PacketConn, error)

NewUDPListener returns a new UDP listener for a given address.

func NewUnixgramListener

func NewUnixgramListener(path string) (net.PacketConn, error)

NewUnixgramListener returns a new unixgram listener for a given path.

func Tag

func Tag(k, v string) string

Tag is an alias / wrapper to stats.Tag

Types

type Client

type Client struct {
	Addr           string
	DialTimeout    time.Duration
	MaxPacketSize  int
	SampleProvider func() bool
	MaxBufferSize  int
	// contains filtered or unexported fields
}

Client is a statsd client.

func New

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

New creates a new statsd client and opens the underlying UDP connection.

func (*Client) AddDefaultTag

func (c *Client) AddDefaultTag(name, value string)

AddDefaultTag adds a new default tag.

func (*Client) AddDefaultTags

func (c *Client) AddDefaultTags(tags ...string)

AddDefaultTags adds default tags.

func (*Client) Close

func (c *Client) Close() error

Close closes the underlying connection.

func (*Client) Count

func (c *Client) Count(name string, value int64, tags ...string) error

Count sends a count message.

func (*Client) DefaultTags

func (c *Client) DefaultTags() []string

DefaultTags returns the default tags.

func (*Client) Distribution

func (c *Client) Distribution(name string, value float64, tags ...string) error

Distribution is an no-op for raw statsd.

func (*Client) Flush

func (c *Client) Flush() error

Flush is a no-op.

func (*Client) Gauge

func (c *Client) Gauge(name string, value float64, tags ...string) error

Gauge sends a point in time value.

func (*Client) Histogram

func (c *Client) Histogram(name string, value float64, tags ...string) error

Histogram is an no-op for raw statsd.

func (*Client) Increment

func (c *Client) Increment(name string, tags ...string) error

Increment sends a count message with a value of (1).

func (*Client) TimeInMilliseconds

func (c *Client) TimeInMilliseconds(name string, value time.Duration, tags ...string) error

TimeInMilliseconds sends a gauge method with a given value represented in milliseconds.

type ClientOpt

type ClientOpt func(*Client) error

ClientOpt is an option for a client.

func OptAddr

func OptAddr(addr string) ClientOpt

OptAddr sets the client address.

func OptConfig

func OptConfig(cfg Config) ClientOpt

OptConfig sets fields on a client from a given config.

func OptDialTimeout

func OptDialTimeout(timeout time.Duration) ClientOpt

OptDialTimeout sets the client dial timeout.

func OptMaxBufferSize

func OptMaxBufferSize(count int) ClientOpt

OptMaxBufferSize sets the client max buffer size in messages.

func OptMaxPacketSize

func OptMaxPacketSize(sizeBytes int) ClientOpt

OptMaxPacketSize sets the client max dial size.

func OptSampleRate

func OptSampleRate(rate float64) ClientOpt

OptSampleRate sets the sample rate on the client or the percent of packets to send on the interval [0,1.0). A value of `0.0` will drop all packets, a value of `1.0` will send all packets.

type Config

type Config struct {
	Addr          string            `json:"addr" yaml:"addr" env:"STATSD_ADDR"`
	DialTimeout   time.Duration     `json:"dialTimeout" yaml:"dialTimeout"`
	SampleRate    float64           `json:"sampleRate" yaml:"sampleRate"`
	MaxPacketSize int               `json:"maxPacketSize" yaml:"maxPacketSize"`
	MaxBufferSize int               `json:"maxBufferSize" yaml:"maxBufferSize"`
	DefaultTags   map[string]string `json:"defaultTags" yaml:"defaultTags"`
}

Config is the set of options for the statsd client.

func (Config) IsZero

func (c Config) IsZero() bool

IsZero returns if the config is set or not.

func (*Config) Resolve

func (c *Config) Resolve(ctx context.Context) error

Resolve implements configutil.Resolver.

type Metric

type Metric struct {
	Name  string
	Type  string
	Value string
	Tags  []string
}

Metric is a statsd metric.

func (Metric) Duration

func (m Metric) Duration() (time.Duration, error)

Duration is the value parsed as a duration assuming it was a float64 of milliseconds.

func (Metric) Float64

func (m Metric) Float64() (float64, error)

Float64 returns the value parsed as a float64.

func (Metric) Int64

func (m Metric) Int64() (int64, error)

Int64 returns the value parsed as an int64.

type Server

type Server struct {
	Addr          string
	Log           *log.Logger
	MaxPacketSize int
	Listener      net.PacketConn
	Handler       func(...Metric)
}

Server is a listener for statsd metrics. It is meant to be used for diagnostic purposes, and is not suitable for production anything.

func (*Server) MaxPacketSizeOrDefault

func (s *Server) MaxPacketSizeOrDefault() int

MaxPacketSizeOrDefault returns the max packet size or a default.

func (*Server) Start

func (s *Server) Start() error

Start starts the server. This call blocks.

func (*Server) Stop

func (s *Server) Stop() error

Stop closes the server.