statsd

package
Version: v3.1.1+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 19, 2018 License: MIT Imports: 10 Imported by: 286

Documentation

Overview

Package statsd provides a StatsD client implementation that is safe for concurrent use by multiple goroutines and for efficiency can be created and reused.

Example usage:

// first create a client
client, err := statsd.NewClient("127.0.0.1:8125", "test-client")
// handle any errors
if err != nil {
	log.Fatal(err)
}
// make sure to clean up
defer client.Close()

// Send a stat
err = client.Inc("stat1", 42, 1.0)
// handle any errors
if err != nil {
	log.Printf("Error sending metric: %+v", err)
}

Index

Examples

Constants

This section is empty.

Variables

View Source
var Dial = NewClient

Dial is a compatibility alias for NewClient

New is a compatibility alias for NewClient

View Source
var NewNoop = NewNoopClient

NewNoop is a compatibility alias for NewNoopClient

Functions

func CheckName

func CheckName(stat string) error

CheckName may be used to validate whether a stat name contains invalid characters. If invalid characters are found, the function will return an error.

func DefaultSampler

func DefaultSampler(rate float32) bool

DefaultSampler is the default rate sampler function

Types

type BufferedSender added in v1.0.1

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

BufferedSender provides a buffered statsd udp, sending multiple metrics, where possible.

func (*BufferedSender) Close added in v1.0.1

func (s *BufferedSender) Close() error

Close Buffered Sender

func (*BufferedSender) Send added in v1.0.1

func (s *BufferedSender) Send(data []byte) (int, error)

Send bytes.

func (*BufferedSender) Start added in v1.0.1

func (s *BufferedSender) Start()

Start Buffered Sender Begins ticker and read loop

type Client

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

A Client is a statsd client.

Example
// first create a client
client, err := NewClient("127.0.0.1:8125", "test-client")
// handle any errors
if err != nil {
	log.Fatal(err)
}
// make sure to clean up
defer client.Close()

// Send a stat
err = client.Inc("stat1", 42, 1.0)
// handle any errors
if err != nil {
	log.Printf("Error sending metric: %+v", err)
}
Output:

Example (Buffered)
// first create a client
client, err := NewBufferedClient("127.0.0.1:8125", "test-client", 10*time.Millisecond, 0)
// handle any errors
if err != nil {
	log.Fatal(err)
}
// make sure to clean up
defer client.Close()

// Send a stat
err = client.Inc("stat1", 42, 1.0)
// handle any errors
if err != nil {
	log.Printf("Error sending metric: %+v", err)
}
Output:

Example (Noop)
// use interface so we can sub noop client if needed
var client Statter
var err error

// first try to create a real client
client, err = NewClient("not-resolvable:8125", "test-client")
// Let us say real client creation fails, but you don't care enough about
// stats that you don't want your program to run. Just log an error and
// make a NoopClient instead
if err != nil {
	log.Println("Remote endpoint did not resolve. Disabling stats", err)
	client, err = NewNoopClient()
}
// make sure to clean up
defer client.Close()

// Send a stat
err = client.Inc("stat1", 42, 1.0)
// handle any errors
if err != nil {
	log.Printf("Error sending metric: %+v", err)
}
Output:

Example (Substatter)
// first create a client
client, err := NewClient("127.0.0.1:8125", "test-client")
// handle any errors
if err != nil {
	log.Fatal(err)
}
// make sure to clean up
defer client.Close()

// create a substatter
subclient := client.NewSubStatter("sub")
// send a stat
err = subclient.Inc("stat1", 42, 1.0)
// handle any errors
if err != nil {
	log.Printf("Error sending metric: %+v", err)
}
Output:

func (*Client) Close

func (s *Client) Close() error

Close closes the connection and cleans up.

func (*Client) Dec

func (s *Client) Dec(stat string, value int64, rate float32) error

Dec decrements a statsd count type. stat is a string name for the metric. value is the integer value. rate is the sample rate (0.0 to 1.0).

func (*Client) Gauge

func (s *Client) Gauge(stat string, value int64, rate float32) error

Gauge submits/updates a statsd gauge type. stat is a string name for the metric. value is the integer value. rate is the sample rate (0.0 to 1.0).

func (*Client) GaugeDelta

func (s *Client) GaugeDelta(stat string, value int64, rate float32) error

GaugeDelta submits a delta to a statsd gauge. stat is the string name for the metric. value is the (positive or negative) change. rate is the sample rate (0.0 to 1.0).

func (*Client) Inc

func (s *Client) Inc(stat string, value int64, rate float32) error

Inc increments a statsd count type. stat is a string name for the metric. value is the integer value rate is the sample rate (0.0 to 1.0)

func (*Client) NewSubStatter

func (s *Client) NewSubStatter(prefix string) SubStatter

NewSubStatter returns a SubStatter with appended prefix

func (*Client) Raw

func (s *Client) Raw(stat string, value string, rate float32) error

Raw submits a preformatted value. stat is the string name for the metric. value is a preformatted "raw" value string. rate is the sample rate (0.0 to 1.0).

func (*Client) Set

func (s *Client) Set(stat string, value string, rate float32) error

Set submits a stats set type stat is a string name for the metric. value is the string value rate is the sample rate (0.0 to 1.0).

func (*Client) SetInt

func (s *Client) SetInt(stat string, value int64, rate float32) error

SetInt submits a number as a stats set type. stat is a string name for the metric. value is the integer value rate is the sample rate (0.0 to 1.0).

func (*Client) SetPrefix

func (s *Client) SetPrefix(prefix string)

SetPrefix sets/updates the statsd client prefix. Note: Does not change the prefix of any SubStatters.

func (*Client) SetSamplerFunc

func (s *Client) SetSamplerFunc(sampler SamplerFunc)

SetSamplerFunc sets a sampler function to something other than the default sampler is a function that determines whether the metric is to be accepted, or discarded. An example use case is for submitted pre-sampled metrics.

func (*Client) Timing

func (s *Client) Timing(stat string, delta int64, rate float32) error

Timing submits a statsd timing type. stat is a string name for the metric. delta is the time duration value in milliseconds rate is the sample rate (0.0 to 1.0).

func (*Client) TimingDuration

func (s *Client) TimingDuration(stat string, delta time.Duration, rate float32) error

TimingDuration submits a statsd timing type. stat is a string name for the metric. delta is the timing value as time.Duration rate is the sample rate (0.0 to 1.0).

type NoopClient

type NoopClient struct{}

A NoopClient is a client that does nothing.

func (*NoopClient) Close

func (s *NoopClient) Close() error

Close closes the connection and cleans up.

func (*NoopClient) Dec

func (s *NoopClient) Dec(stat string, value int64, rate float32) error

Dec decrements a statsd count type. stat is a string name for the metric. value is the integer value. rate is the sample rate (0.0 to 1.0).

func (*NoopClient) Gauge

func (s *NoopClient) Gauge(stat string, value int64, rate float32) error

Gauge submits/Updates a statsd gauge type. stat is a string name for the metric. value is the integer value. rate is the sample rate (0.0 to 1.0).

func (*NoopClient) GaugeDelta

func (s *NoopClient) GaugeDelta(stat string, value int64, rate float32) error

GaugeDelta submits a delta to a statsd gauge. stat is the string name for the metric. value is the (positive or negative) change. rate is the sample rate (0.0 to 1.0).

func (*NoopClient) Inc

func (s *NoopClient) Inc(stat string, value int64, rate float32) error

Inc increments a statsd count type. stat is a string name for the metric. value is the integer value rate is the sample rate (0.0 to 1.0)

func (*NoopClient) NewSubStatter

func (s *NoopClient) NewSubStatter(prefix string) SubStatter

NewSubStatter returns a SubStatter with appended prefix

func (*NoopClient) Raw

func (s *NoopClient) Raw(stat string, value string, rate float32) error

Raw formats the statsd event data, handles sampling, prepares it, and sends it to the server. stat is the string name for the metric. value is the preformatted "raw" value string. rate is the sample rate (0.0 to 1.0).

func (*NoopClient) Set

func (s *NoopClient) Set(stat string, value string, rate float32) error

Set submits a stats set type. stat is a string name for the metric. value is the string value rate is the sample rate (0.0 to 1.0).

func (*NoopClient) SetInt

func (s *NoopClient) SetInt(stat string, value int64, rate float32) error

SetInt submits a number as a stats set type. convenience method for Set with number. stat is a string name for the metric. value is the integer value rate is the sample rate (0.0 to 1.0).

func (*NoopClient) SetPrefix

func (s *NoopClient) SetPrefix(prefix string)

SetPrefix sets/updates the statsd client prefix

func (*NoopClient) SetSamplerFunc

func (s *NoopClient) SetSamplerFunc(sampler SamplerFunc)

SetSamplerFunc sets the sampler function

func (*NoopClient) Timing

func (s *NoopClient) Timing(stat string, delta int64, rate float32) error

Timing submits a statsd timing type. stat is a string name for the metric. delta is the time duration value in milliseconds rate is the sample rate (0.0 to 1.0).

func (*NoopClient) TimingDuration

func (s *NoopClient) TimingDuration(stat string, delta time.Duration, rate float32) error

TimingDuration submits a statsd timing type. stat is a string name for the metric. delta is the timing value as time.Duration rate is the sample rate (0.0 to 1.0).

type SamplerFunc

type SamplerFunc func(float32) bool

The SamplerFunc type defines a function that can serve as a Client sampler function.

type Sender added in v1.0.1

type Sender interface {
	Send(data []byte) (int, error)
	Close() error
}

The Sender interface wraps a Send and Close

func NewBufferedSender added in v1.0.1

func NewBufferedSender(addr string, flushInterval time.Duration, flushBytes int) (Sender, error)

NewBufferedSender returns a new BufferedSender

addr is a string of the format "hostname:port", and must be parsable by net.ResolveUDPAddr.

flushInterval is a time.Duration, and specifies the maximum interval for packet sending. Note that if you send lots of metrics, you will send more often. This is just a maximal threshold.

flushBytes specifies the maximum udp packet size you wish to send. If adding a metric would result in a larger packet than flushBytes, the packet will first be send, then the new data will be added to the next packet.

func NewSimpleSender added in v1.0.1

func NewSimpleSender(addr string) (Sender, error)

NewSimpleSender returns a new SimpleSender for sending to the supplied addresss.

addr is a string of the format "hostname:port", and must be parsable by net.ResolveUDPAddr.

type SimpleSender added in v1.0.1

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

SimpleSender provides a socket send interface.

func (*SimpleSender) Close added in v1.0.1

func (s *SimpleSender) Close() error

Close closes the SimpleSender

func (*SimpleSender) Send added in v1.0.1

func (s *SimpleSender) Send(data []byte) (int, error)

Send sends the data to the server endpoint.

type StatSender

type StatSender interface {
	Inc(string, int64, float32) error
	Dec(string, int64, float32) error
	Gauge(string, int64, float32) error
	GaugeDelta(string, int64, float32) error
	Timing(string, int64, float32) error
	TimingDuration(string, time.Duration, float32) error
	Set(string, string, float32) error
	SetInt(string, int64, float32) error
	Raw(string, string, float32) error
}

The StatSender interface wraps all the statsd metric methods

type Statter

type Statter interface {
	StatSender
	NewSubStatter(string) SubStatter
	SetPrefix(string)
	Close() error
}

The Statter interface defines the behavior of a stat client

func NewBufferedClient added in v1.0.1

func NewBufferedClient(addr, prefix string, flushInterval time.Duration, flushBytes int) (Statter, error)

NewBufferedClient returns a new BufferedClient

addr is a string of the format "hostname:port", and must be parsable by net.ResolveUDPAddr.

prefix is the statsd client prefix. Can be "" if no prefix is desired.

flushInterval is a time.Duration, and specifies the maximum interval for packet sending. Note that if you send lots of metrics, you will send more often. This is just a maximal threshold.

If flushInterval is 0ms, defaults to 300ms.

flushBytes specifies the maximum udp packet size you wish to send. If adding a metric would result in a larger packet than flushBytes, the packet will first be send, then the new data will be added to the next packet.

If flushBytes is 0, defaults to 1432 bytes, which is considered safe for local traffic. If sending over the public internet, 512 bytes is the recommended value.

func NewClient added in v1.0.1

func NewClient(addr, prefix string) (Statter, error)

NewClient returns a pointer to a new Client, and an error.

addr is a string of the format "hostname:port", and must be parsable by net.ResolveUDPAddr.

prefix is the statsd client prefix. Can be "" if no prefix is desired.

func NewClientWithSender

func NewClientWithSender(sender Sender, prefix string) (Statter, error)

NewClientWithSender returns a pointer to a new Client and an error.

sender is an instance of a statsd.Sender interface and may not be nil

prefix is the stastd client prefix. Can be "" if no prefix is desired.

func NewNoopClient added in v1.0.1

func NewNoopClient(a ...interface{}) (Statter, error)

NewNoopClient returns a pointer to a new NoopClient, and an error (always nil, just supplied to support api convention). Use variadic arguments to support identical format as NewClient, or a more conventional no argument form.

type SubStatter

type SubStatter interface {
	StatSender
	SetSamplerFunc(SamplerFunc)
	NewSubStatter(string) SubStatter
}

The SubStatter interface defines the behavior of a stat child/subclient

type ValidatorFunc

type ValidatorFunc func(string) error

The ValidatorFunc type defines a function that can serve as a stat name validation function.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL