statsd

package
v4.0.0 Latest Latest
Warning

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

 Go to latest Published: Nov 6, 2020 License: MIT Imports: 10 Imported by: 2

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 config. Here is a simple config that sends one
// stat per packet (for compatibility).
config := &statsd.ClientConfig{
    Address: "127.0.0.1:8125",
    Prefix: "test-client",
}

// Now create the client
client, err := statsd.NewClientWithConfig(config)

// and handle any initialization 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

Deprecated: This interface is "legacy", and it is recommented to migrate to using NewClientWithConfig in the future.

View Source 
var New = NewClient

New is a compatibility alias for NewClient

Deprecated: This interface is "legacy", and it is recommented to migrate to using NewClientWithConfig in the future.

View Source 
var NewNoop = NewNoopClient

NewNoop is a compatibility alias for NewNoopClient

Deprecated: This type is "legacy", and it is recommented to migrate to using a nil *Client in the future.

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 

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

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

func (*BufferedSender) Close 

func (s *BufferedSender) Close() error

Close closes the Buffered Sender and cleans up.

func (*BufferedSender) Send 

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

Send bytes.

func (*BufferedSender) Start 

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 config. Here is a simple config that sends one
// stat per packet (for compatibility).
config := &ClientConfig{
	Address: "127.0.0.1:8125",
	Prefix:  "test-client",
}

// Now create the client
client, err := NewClientWithConfig(config)

// and handle any initialization 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) 
// This one is for a buffered client, which sends multiple stats in one
// packet, is recommended when your server supports it (better performance).
config := &ClientConfig{
	Address:     "127.0.0.1:8125",
	Prefix:      "test-client",
	UseBuffered: true,
	// interval to force flush buffer. full buffers will flush on their own,
	// but for data not frequently sent, a max threshold is useful
	FlushInterval: 300 * time.Millisecond,
}

// Now create the client
client, err := NewClientWithConfig(config)

// and handle any initialization errors
if err != nil {
	log.Fatal(err)
}

// make sure to close to clean up when done, to avoid leaks.
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 (LegacyBuffered) 
// 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 close to clean up when done, to avoid leaks.
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 (LegacySimple) 
// 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 close to clean up when done, to avoid leaks.
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 create a client config. Here is a simple config that sends one
// stat per packet (for compatibility).
config := &ClientConfig{
	Address: "not-resolvable:8125",
	Prefix:  "test-client",
}

// Now create the client
client, err = NewClientWithConfig(config)

// 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)
}
// at this point, client is a nil *Client. This will work like a noop client.
// It is ok to call close when client is nil. It will be a noop too.
defer client.Close()

// Sicne client is nil, this is a noop.
err = client.Inc("stat1", 42, 1.0)

Output:
Example (Substatter) 
// First create a client config. Here is a simple config that sends one
// stat per packet (for compatibility).
config := &ClientConfig{
	Address: "127.0.0.1:8125",
	Prefix:  "test-client",
}

// Now create the client
client, err := NewClientWithConfig(config)
// handle any errors
if err != nil {
	log.Fatal(err)
}
// make sure to close to clean up when done, to avoid leaks.
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 ClientConfig 

type ClientConfig struct {
	// addr is a string of the format "hostname:port", and must be something
	// validly parsable by net.ResolveUDPAddr.
	Address string

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

	// ResInterval is the interval over which the addr is re-resolved.
	// Do note that this /does/ add overhead!
	// If you need higher performance, leave unset (or set to 0),
	// in which case the address will not be re-resolved.
	//
	// Note that if Address is an {ip}:{port} and not a {hostname}:{port}, then
	// ResInterval will be ignored.
	ResInterval time.Duration

	// UseBuffered determines whether a buffered sender is used or not.
	// If a buffered sender is /not/ used, FlushInterval and FlushBytes values are
	// ignored. Default is false.
	UseBuffered bool

	// 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 0, defaults to 300ms.
	FlushInterval time.Duration

	// 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.
	FlushBytes int
}

type NoopClient deprecated 

type NoopClient struct{}

A NoopClient is a client that does nothing.

Deprecated: This type is "legacy", and it is recommented to migrate to using a nil *Client in the future.

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 ResolvingSimpleSender 

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

ResolvingSimpleSender provides a socket send interface that re-resolves and reconnects.

func (*ResolvingSimpleSender) Close 

func (s *ResolvingSimpleSender) Close() error

Close closes the ResolvingSender and cleans up

func (*ResolvingSimpleSender) Reconnect 

func (s *ResolvingSimpleSender) Reconnect()

func (*ResolvingSimpleSender) Send 

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

Send sends the data to the server endpoint.

func (*ResolvingSimpleSender) Start 

func (s *ResolvingSimpleSender) Start()

Start Resolving Simple Sender Begins ticker and read loop

type SamplerFunc 

type SamplerFunc func(float32) bool

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

type Sender 

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

The Sender interface wraps a Send and Close

func NewBufferedSender 

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 NewBufferedSenderWithSender 

func NewBufferedSenderWithSender(sender Sender, flushInterval time.Duration, flushBytes int) (Sender, error)

NewBufferedSenderWithSender returns a new BufferedSender, wrapping the provided sender.

sender is an instance of a statsd.Sender interface. Sender is required.

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 NewResolvingSimpleSender 

func NewResolvingSimpleSender(addr string, interval time.Duration) (Sender, error)

NewResolvingSimpleSender returns a new ResolvingSimpleSender for sending to the supplied addresss.

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

func NewSimpleSender 

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 

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

SimpleSender provides a socket send interface.

func (*SimpleSender) Close 

func (s *SimpleSender) Close() error

Close closes the SimpleSender and cleans up.

func (*SimpleSender) Send 

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 deprecated 

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.

Deprecated: This interface is "legacy", and it is recommented to migrate to using NewClientWithConfig in the future.

func NewClient deprecated 

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.

Deprecated: This interface is "legacy", and it is recommented to migrate to using NewClientWithConfig in the future.

func NewClientWithConfig 

func NewClientWithConfig(config *ClientConfig) (Statter, error)

NewClientWithConfig returns a new BufferedClient

config is a ClientConfig, which holds various configuration values.

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 deprecated 

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.

Deprecated: This type is "legacy", and it is recommented to migrate to using a nil *Client in the future.

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.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.