statsd

package
v2.3.0+incompatible Latest Latest
Warning

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

Go to latest
Published: Oct 15, 2019 License: MIT Imports: 11 Imported by: 0

README

Overview

Package statsd provides a Go dogstatsd client. Dogstatsd extends Statsd, adding tags and histograms.

Documentation

Overview

Package statsd provides a Go dogstatsd client. Dogstatsd extends the popular statsd, adding tags and histograms and pushing upstream to Datadog.

Refer to http://docs.datadoghq.com/guides/dogstatsd/ for information about DogStatsD.

Example Usage:

// Create the client
c, err := statsd.New("127.0.0.1:8125")
if err != nil {
    log.Fatal(err)
}
// Prefix every metric with the app name
c.Namespace = "flubber."
// Send the EC2 availability zone as a tag with every metric
c.Tags = append(c.Tags, "us-east-1a")
err = c.Gauge("request.duration", 1.2, nil, 1)

statsd is based on go-statsd-client.

Index

Constants

View Source
const ErrNoClient = noClientErr("statsd client is nil")

ErrNoClient is returned if statsd reporting methods are invoked on a nil client.

View Source
const MaxUDPPayloadSize = 65467

MaxUDPPayloadSize defines the maximum payload size for a UDP datagram. Its value comes from the calculation: 65535 bytes Max UDP datagram size - 8byte UDP header - 60byte max IP headers any number greater than that will see frames being cut out.

View Source
const OptimalPayloadSize = 1432

OptimalPayloadSize defines the optimal payload size for a UDP datagram, 1432 bytes is optimal for regular networks with an MTU of 1500 so datagrams don't get fragmented. It's generally recommended not to fragment UDP datagrams as losing a single fragment will cause the entire datagram to be lost.

This can be increased if your network has a greater MTU or you don't mind UDP datagrams getting fragmented. The practical limit is MaxUDPPayloadSize

View Source
const UnixAddressPrefix = "unix://"

UnixAddressPrefix holds the prefix to use to enable Unix Domain Socket traffic instead of UDP.

Variables

View Source
var (
	// DefaultNamespace is the default value for the Namespace option
	DefaultNamespace = ""
	// DefaultTags is the default value for the Tags option
	DefaultTags = []string{}
	// DefaultBuffered is the default value for the Buffered option
	DefaultBuffered = false
	// DefaultMaxMessagesPerPayload is the default value for the MaxMessagesPerPayload option
	DefaultMaxMessagesPerPayload = 16
	// DefaultAsyncUDS is the default value for the AsyncUDS option
	DefaultAsyncUDS = false
	// DefaultWriteTimeoutUDS is the default value for the WriteTimeoutUDS option
	DefaultWriteTimeoutUDS = 1 * time.Millisecond
)

Functions

This section is empty.

Types

type Client

type Client struct {

	// Namespace to prepend to all statsd calls
	Namespace string
	// Tags are global tags to be added to every statsd call
	Tags []string
	// skipErrors turns off error passing and allows UDS to emulate UDP behaviour
	SkipErrors bool

	sync.Mutex
	// contains filtered or unexported fields
}

A Client is a handle for sending messages to dogstatsd. It is safe to use one Client from multiple goroutines simultaneously.

func New

func New(addr string, options ...Option) (*Client, error)

New returns a pointer to a new Client given an addr in the format "hostname:port" or "unix:///path/to/socket".

func NewBuffered

func NewBuffered(addr string, buflen int) (*Client, error)

NewBuffered returns a Client that buffers its output and sends it in chunks. Buflen is the length of the buffer in number of commands.

When addr is empty, the client will default to a UDP client and use the DD_AGENT_HOST and (optionally) the DD_DOGSTATSD_PORT environment variables to build the target address.

func NewWithWriter

func NewWithWriter(w statsdWriter) (*Client, error)

NewWithWriter creates a new Client with given writer. Writer is a io.WriteCloser + SetWriteTimeout(time.Duration) error

func (*Client) Close

func (c *Client) Close() error

Close the client connection.

func (*Client) Count

func (c *Client) Count(name string, value int64, tags []string, rate float64) error

Count tracks how many times something happened per second.

func (*Client) Decr

func (c *Client) Decr(name string, tags []string, rate float64) error

Decr is just Count of -1

func (*Client) Distribution

func (c *Client) Distribution(name string, value float64, tags []string, rate float64) error

Distribution tracks the statistical distribution of a set of values across your infrastructure.

func (*Client) Event

func (c *Client) Event(e *Event) error

Event sends the provided Event.

func (*Client) Flush

func (c *Client) Flush() error

Flush forces a flush of the pending commands in the buffer

func (*Client) Gauge

func (c *Client) Gauge(name string, value float64, tags []string, rate float64) error

Gauge measures the value of a metric at a particular time.

func (*Client) Histogram

func (c *Client) Histogram(name string, value float64, tags []string, rate float64) error

Histogram tracks the statistical distribution of a set of values on each host.

func (*Client) Incr

func (c *Client) Incr(name string, tags []string, rate float64) error

Incr is just Count of 1

func (*Client) ServiceCheck

func (c *Client) ServiceCheck(sc *ServiceCheck) error

ServiceCheck sends the provided ServiceCheck.

func (*Client) Set

func (c *Client) Set(name string, value string, tags []string, rate float64) error

Set counts the number of unique elements in a group.

func (*Client) SetWriteTimeout

func (c *Client) SetWriteTimeout(d time.Duration) error

SetWriteTimeout allows the user to set a custom UDS write timeout. Not supported for UDP.

func (*Client) SimpleEvent

func (c *Client) SimpleEvent(title, text string) error

SimpleEvent sends an event with the provided title and text.

func (*Client) SimpleServiceCheck

func (c *Client) SimpleServiceCheck(name string, status ServiceCheckStatus) error

SimpleServiceCheck sends an serviceCheck with the provided name and status.

func (*Client) TimeInMilliseconds

func (c *Client) TimeInMilliseconds(name string, value float64, tags []string, rate float64) error

TimeInMilliseconds sends timing information in milliseconds. It is flushed by statsd with percentiles, mean and other info (https://github.com/etsy/statsd/blob/master/docs/metric_types.md#timing)

func (*Client) Timing

func (c *Client) Timing(name string, value time.Duration, tags []string, rate float64) error

Timing sends timing information, it is an alias for TimeInMilliseconds

type Event

type Event struct {
	// Title of the event.  Required.
	Title string
	// Text is the description of the event.  Required.
	Text string
	// Timestamp is a timestamp for the event.  If not provided, the dogstatsd
	// server will set this to the current time.
	Timestamp time.Time
	// Hostname for the event.
	Hostname string
	// AggregationKey groups this event with others of the same key.
	AggregationKey string
	// Priority of the event.  Can be statsd.Low or statsd.Normal.
	Priority EventPriority
	// SourceTypeName is a source type for the event.
	SourceTypeName string
	// AlertType can be statsd.Info, statsd.Error, statsd.Warning, or statsd.Success.
	// If absent, the default value applied by the dogstatsd server is Info.
	AlertType EventAlertType
	// Tags for the event.
	Tags []string
}

An Event is an object that can be posted to your DataDog event stream.

func NewEvent

func NewEvent(title, text string) *Event

NewEvent creates a new event with the given title and text. Error checking against these values is done at send-time, or upon running e.Check.

func (Event) Check

func (e Event) Check() error

Check verifies that an event is valid.

func (Event) Encode

func (e Event) Encode(tags ...string) (string, error)

Encode returns the dogstatsd wire protocol representation for an event. Tags may be passed which will be added to the encoded output but not to the Event's list of tags, eg. for default tags.

type EventAlertType

type EventAlertType string

EventAlertType is the alert type for events

const (
	// Info is the "info" AlertType for events
	Info EventAlertType = "info"
	// Error is the "error" AlertType for events
	Error EventAlertType = "error"
	// Warning is the "warning" AlertType for events
	Warning EventAlertType = "warning"
	// Success is the "success" AlertType for events
	Success EventAlertType = "success"
)

type EventPriority

type EventPriority string

EventPriority is the event priority for events

const (
	// Normal is the "normal" Priority for events
	Normal EventPriority = "normal"
	// Low is the "low" Priority for events
	Low EventPriority = "low"
)

type Option

type Option func(*Options) error

Option is a client option. Can return an error if validation fails.

func Buffered

func Buffered() Option

Buffered sets the Buffered option.

func WithAsyncUDS

func WithAsyncUDS() Option

WithAsyncUDS sets the AsyncUDS option.

func WithMaxMessagesPerPayload

func WithMaxMessagesPerPayload(maxMessagesPerPayload int) Option

WithMaxMessagesPerPayload sets the MaxMessagesPerPayload option.

func WithNamespace

func WithNamespace(namespace string) Option

WithNamespace sets the Namespace option.

func WithTags

func WithTags(tags []string) Option

WithTags sets the Tags option.

func WithWriteTimeoutUDS

func WithWriteTimeoutUDS(writeTimeoutUDS time.Duration) Option

WithWriteTimeoutUDS sets the WriteTimeoutUDS option.

type Options

type Options struct {
	// Namespace to prepend to all metrics, events and service checks name.
	Namespace string
	// Tags are global tags to be applied to every metrics, events and service checks.
	Tags []string
	// Buffered allows to pack multiple DogStatsD messages in one payload. Messages will be buffered
	// until the total size of the payload exceeds MaxMessagesPerPayload metrics, events and/or service
	// checks or after 100ms since the payload startedto be built.
	Buffered bool
	// MaxMessagesPerPayload is the maximum number of metrics, events and/or service checks a single payload will contain.
	// Note that this option only takes effect when the client is buffered.
	MaxMessagesPerPayload int
	// AsyncUDS allows to switch between async and blocking mode for UDS.
	// Blocking mode allows for error checking but does not guarentee that calls won't block the execution.
	AsyncUDS bool
	// WriteTimeoutUDS is the timeout after which a UDS packet is dropped.
	WriteTimeoutUDS time.Duration
}

Options contains the configuration options for a client.

type ServiceCheck

type ServiceCheck struct {
	// Name of the service check.  Required.
	Name string
	// Status of service check.  Required.
	Status ServiceCheckStatus
	// Timestamp is a timestamp for the serviceCheck.  If not provided, the dogstatsd
	// server will set this to the current time.
	Timestamp time.Time
	// Hostname for the serviceCheck.
	Hostname string
	// A message describing the current state of the serviceCheck.
	Message string
	// Tags for the serviceCheck.
	Tags []string
}

An ServiceCheck is an object that contains status of DataDog service check.

func NewServiceCheck

func NewServiceCheck(name string, status ServiceCheckStatus) *ServiceCheck

NewServiceCheck creates a new serviceCheck with the given name and status. Error checking against these values is done at send-time, or upon running sc.Check.

func (ServiceCheck) Check

func (sc ServiceCheck) Check() error

Check verifies that an event is valid.

func (ServiceCheck) Encode

func (sc ServiceCheck) Encode(tags ...string) (string, error)

Encode returns the dogstatsd wire protocol representation for an serviceCheck. Tags may be passed which will be added to the encoded output but not to the Event's list of tags, eg. for default tags.

type ServiceCheckStatus

type ServiceCheckStatus byte

ServiceCheckStatus support

const (
	// Ok is the "ok" ServiceCheck status
	Ok ServiceCheckStatus = 0
	// Warn is the "warning" ServiceCheck status
	Warn ServiceCheckStatus = 1
	// Critical is the "critical" ServiceCheck status
	Critical ServiceCheckStatus = 2
	// Unknown is the "unknown" ServiceCheck status
	Unknown ServiceCheckStatus = 3
)

Jump to

Keyboard shortcuts

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