datadog-go: github.com/DataDog/datadog-go/statsd Index | Files

package statsd

import "github.com/DataDog/datadog-go/statsd"

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

Package Files

buffer.go buffer_pool.go event.go format.go noop.go options.go sender.go service_check.go statsd.go udp.go uds.go

Constants

const DefaultMaxAgentPayloadSize = 8192

DefaultMaxAgentPayloadSize is the default maximum payload size the agent can receive. This can be adjusted by changing dogstatsd_buffer_size in the agent configuration file datadog.yaml.

const DefaultUDPBufferPoolSize = 2048

DefaultUDPBufferPoolSize is the default size of the buffer pool for UDP clients.

const DefaultUDSBufferPoolSize = 512

DefaultUDSBufferPoolSize is the default size of the buffer pool for UDS clients.

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

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

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.

const OptimalUDPPayloadSize = 1432

OptimalUDPPayloadSize 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.

const TelemetryInterval = 10 * time.Second

TelemetryInterval is the interval at which telemetry will be sent by the client.

const UnixAddressPrefix = "unix://"

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

Variables

var (
    // DefaultNamespace is the default value for the Namespace option
    DefaultNamespace = ""
    // DefaultTags is the default value for the Tags option
    DefaultTags = []string{}
    // DefaultMaxBytesPerPayload is the default value for the MaxBytesPerPayload option
    DefaultMaxBytesPerPayload = 0
    // DefaultMaxMessagesPerPayload is the default value for the MaxMessagesPerPayload option
    DefaultMaxMessagesPerPayload = math.MaxInt32
    // DefaultBufferPoolSize is the default value for the DefaultBufferPoolSize option
    DefaultBufferPoolSize = 0
    // DefaultBufferFlushInterval is the default value for the BufferFlushInterval option
    DefaultBufferFlushInterval = 100 * time.Millisecond
    // DefaultSenderQueueSize is the default value for the DefaultSenderQueueSize option
    DefaultSenderQueueSize = 0
    // DefaultWriteTimeoutUDS is the default value for the WriteTimeoutUDS option
    DefaultWriteTimeoutUDS = 1 * time.Millisecond
)

type Client Uses

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 Uses

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 Uses

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 Uses

func NewWithWriter(w statsdWriter, options ...Option) (*Client, error)

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

func (*Client) Close Uses

func (c *Client) Close() error

Close the client connection.

func (*Client) Count Uses

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 Uses

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

Decr is just Count of -1

func (*Client) Distribution Uses

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 Uses

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

Event sends the provided Event.

func (*Client) Flush Uses

func (c *Client) Flush() error

Flush forces a flush of all the queued dogstatsd payloads This method is blocking and will not return until everything is sent through the network

func (*Client) Gauge Uses

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 Uses

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 Uses

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

Incr is just Count of 1

func (*Client) ServiceCheck Uses

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

ServiceCheck sends the provided ServiceCheck.

func (*Client) Set Uses

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 Uses

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 Uses

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

SimpleEvent sends an event with the provided title and text.

func (*Client) SimpleServiceCheck Uses

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

SimpleServiceCheck sends an serviceCheck with the provided name and status.

func (*Client) TimeInMilliseconds Uses

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 Uses

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 ClientInterface Uses

type ClientInterface interface {
    // Gauge measures the value of a metric at a particular time.
    Gauge(name string, value float64, tags []string, rate float64) error

    // Count tracks how many times something happened per second.
    Count(name string, value int64, tags []string, rate float64) error

    // Histogram tracks the statistical distribution of a set of values on each host.
    Histogram(name string, value float64, tags []string, rate float64) error

    // Distribution tracks the statistical distribution of a set of values across your infrastructure.
    Distribution(name string, value float64, tags []string, rate float64) error

    // Decr is just Count of -1
    Decr(name string, tags []string, rate float64) error

    // Incr is just Count of 1
    Incr(name string, tags []string, rate float64) error

    // Set counts the number of unique elements in a group.
    Set(name string, value string, tags []string, rate float64) error

    // Timing sends timing information, it is an alias for TimeInMilliseconds
    Timing(name string, value time.Duration, 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)
    TimeInMilliseconds(name string, value float64, tags []string, rate float64) error

    // Event sends the provided Event.
    Event(e *Event) error

    // SimpleEvent sends an event with the provided title and text.
    SimpleEvent(title, text string) error

    // ServiceCheck sends the provided ServiceCheck.
    ServiceCheck(sc *ServiceCheck) error

    // SimpleServiceCheck sends an serviceCheck with the provided name and status.
    SimpleServiceCheck(name string, status ServiceCheckStatus) error

    // Close the client connection.
    Close() error

    // Flush forces a flush of all the queued dogstatsd payloads.
    Flush() error

    // SetWriteTimeout allows the user to set a custom write timeout.
    SetWriteTimeout(d time.Duration) error
}

ClientInterface is an interface that exposes the common client functions for the purpose of being able to provide a no-op client or even mocking. This can aid downstream users' with their testing.

type Event Uses

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 Uses

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 Uses

func (e Event) Check() error

Check verifies that an event is valid.

func (Event) Encode Uses

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 Uses

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 Uses

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 NoOpClient Uses

type NoOpClient struct{}

NoOpClient is a statsd client that does nothing. Can be useful in testing situations for library users.

func (*NoOpClient) Close Uses

func (n *NoOpClient) Close() error

Close does nothing and returns nil

func (*NoOpClient) Count Uses

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

Count does nothing and returns nil

func (*NoOpClient) Decr Uses

func (n *NoOpClient) Decr(name string, tags []string, rate float64) error

Decr does nothing and returns nil

func (*NoOpClient) Distribution Uses

func (n *NoOpClient) Distribution(name string, value float64, tags []string, rate float64) error

Distribution does nothing and returns nil

func (*NoOpClient) Event Uses

func (n *NoOpClient) Event(e *Event) error

Event does nothing and returns nil

func (*NoOpClient) Flush Uses

func (n *NoOpClient) Flush() error

Flush does nothing and returns nil

func (*NoOpClient) Gauge Uses

func (n *NoOpClient) Gauge(name string, value float64, tags []string, rate float64) error

Gauge does nothing and returns nil

func (*NoOpClient) Histogram Uses

func (n *NoOpClient) Histogram(name string, value float64, tags []string, rate float64) error

Histogram does nothing and returns nil

func (*NoOpClient) Incr Uses

func (n *NoOpClient) Incr(name string, tags []string, rate float64) error

Incr does nothing and returns nil

func (*NoOpClient) ServiceCheck Uses

func (n *NoOpClient) ServiceCheck(sc *ServiceCheck) error

ServiceCheck does nothing and returns nil

func (*NoOpClient) Set Uses

func (n *NoOpClient) Set(name string, value string, tags []string, rate float64) error

Set does nothing and returns nil

func (*NoOpClient) SetWriteTimeout Uses

func (n *NoOpClient) SetWriteTimeout(d time.Duration) error

SetWriteTimeout does nothing and returns nil

func (*NoOpClient) SimpleEvent Uses

func (n *NoOpClient) SimpleEvent(title, text string) error

SimpleEvent does nothing and returns nil

func (*NoOpClient) SimpleServiceCheck Uses

func (n *NoOpClient) SimpleServiceCheck(name string, status ServiceCheckStatus) error

SimpleServiceCheck does nothing and returns nil

func (*NoOpClient) TimeInMilliseconds Uses

func (n *NoOpClient) TimeInMilliseconds(name string, value float64, tags []string, rate float64) error

TimeInMilliseconds does nothing and returns nil

func (*NoOpClient) Timing Uses

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

Timing does nothing and returns nil

type Option Uses

type Option func(*Options) error

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

func WithBufferFlushInterval Uses

func WithBufferFlushInterval(bufferFlushInterval time.Duration) Option

WithBufferFlushInterval sets the BufferFlushInterval option.

func WithBufferPoolSize Uses

func WithBufferPoolSize(bufferPoolSize int) Option

WithBufferPoolSize sets the BufferPoolSize option.

func WithMaxBytesPerPayload Uses

func WithMaxBytesPerPayload(MaxBytesPerPayload int) Option

WithMaxBytesPerPayload sets the MaxBytesPerPayload option.

func WithMaxMessagesPerPayload Uses

func WithMaxMessagesPerPayload(maxMessagesPerPayload int) Option

WithMaxMessagesPerPayload sets the MaxMessagesPerPayload option.

func WithNamespace Uses

func WithNamespace(namespace string) Option

WithNamespace sets the Namespace option.

func WithSenderQueueSize Uses

func WithSenderQueueSize(senderQueueSize int) Option

WithSenderQueueSize sets the SenderQueueSize option.

func WithTags Uses

func WithTags(tags []string) Option

WithTags sets the Tags option.

func WithWriteTimeoutUDS Uses

func WithWriteTimeoutUDS(writeTimeoutUDS time.Duration) Option

WithWriteTimeoutUDS sets the WriteTimeoutUDS option.

type Options Uses

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
    // MaxBytesPerPayload is the maximum number of bytes a single payload will contain.
    // The magic value 0 will set the option to the optimal size for the transport
    // protocol used when creating the client: 1432 for UDP and 8192 for UDS.
    MaxBytesPerPayload int
    // MaxMessagesPerPayload is the maximum number of metrics, events and/or service checks a single payload will contain.
    // This option can be set to `1` to create an unbuffered client.
    MaxMessagesPerPayload int
    // BufferPoolSize is the size of the pool of buffers in number of buffers.
    // The magic value 0 will set the option to the optimal size for the transport
    // protocol used when creating the client: 2048 for UDP and 512 for UDS.
    BufferPoolSize int
    // BufferFlushInterval is the interval after which the current buffer will get flushed.
    BufferFlushInterval time.Duration
    // SenderQueueSize is the size of the sender queue in number of buffers.
    // The magic value 0 will set the option to the optimal size for the transport
    // protocol used when creating the client: 2048 for UDP and 512 for UDS.
    SenderQueueSize int
    // WriteTimeoutUDS is the timeout after which a UDS packet is dropped.
    WriteTimeoutUDS time.Duration
}

Options contains the configuration options for a client.

type SenderMetrics Uses

type SenderMetrics struct {
    TotalSentBytes                uint64
    TotalSentPayloads             uint64
    TotalDroppedPayloads          uint64
    TotalDroppedBytes             uint64
    TotalDroppedPayloadsQueueFull uint64
    TotalDroppedBytesQueueFull    uint64
    TotalDroppedPayloadsWriter    uint64
    TotalDroppedBytesWriter       uint64
}

SenderMetrics contains metrics about the health of the sender

type ServiceCheck Uses

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
}

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

func NewServiceCheck Uses

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 Uses

func (sc ServiceCheck) Check() error

Check verifies that a service check is valid.

func (ServiceCheck) Encode Uses

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

Encode returns the dogstatsd wire protocol representation for a service check. Tags may be passed which will be added to the encoded output but not to the Service Check's list of tags, eg. for default tags.

type ServiceCheckStatus Uses

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
)

Package statsd imports 11 packages (graph) and is imported by 174 packages. Updated 2019-10-25. Refresh now. Tools for package owners.