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
- Variables
- type Client
- func (c *Client) Close() error
- func (c *Client) Count(name string, value int64, tags []string, rate float64) error
- func (c *Client) Decr(name string, tags []string, rate float64) error
- func (c *Client) Distribution(name string, value float64, tags []string, rate float64) error
- func (c *Client) Event(e *Event) error
- func (c *Client) Flush() error
- func (c *Client) Gauge(name string, value float64, tags []string, rate float64) error
- func (c *Client) Histogram(name string, value float64, tags []string, rate float64) error
- func (c *Client) Incr(name string, tags []string, rate float64) error
- func (c *Client) ServiceCheck(sc *ServiceCheck) error
- func (c *Client) Set(name string, value string, tags []string, rate float64) error
- func (c *Client) SetWriteTimeout(d time.Duration) error
- func (c *Client) SimpleEvent(title, text string) error
- func (c *Client) SimpleServiceCheck(name string, status ServiceCheckStatus) error
- func (c *Client) TimeInMilliseconds(name string, value float64, tags []string, rate float64) error
- func (c *Client) Timing(name string, value time.Duration, tags []string, rate float64) error
- type Event
- type EventAlertType
- type EventPriority
- type Option
- type Options
- type ServiceCheck
- type ServiceCheckStatus
Constants ¶
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 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
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{} // 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 ¶
New returns a pointer to a new Client given an addr in the format "hostname:port" or "unix:///path/to/socket".
func NewBuffered ¶
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 ¶
NewWithWriter creates a new Client with given writer. Writer is a io.WriteCloser + SetWriteTimeout(time.Duration) error
func (*Client) Distribution ¶
Distribution tracks the statistical distribution of a set of values across your infrastructure.
func (*Client) Histogram ¶
Histogram tracks the statistical distribution of a set of values on each host.
func (*Client) ServiceCheck ¶
func (c *Client) ServiceCheck(sc *ServiceCheck) error
ServiceCheck sends the provided ServiceCheck.
func (*Client) SetWriteTimeout ¶
SetWriteTimeout allows the user to set a custom UDS write timeout. Not supported for UDP.
func (*Client) SimpleEvent ¶
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 ¶
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)
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.
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 ¶
Option is a client option. Can return an error if validation fails.
func WithMaxMessagesPerPayload ¶
WithMaxMessagesPerPayload sets the MaxMessagesPerPayload option.
func WithNamespace ¶
WithNamespace sets the Namespace option.
func WithWriteTimeoutUDS ¶
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.
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 )
Source Files