README
¶
go-statsd
Forked from https://github.com/alexcesaro/statsd on 2017-12-23 to add some missing bits. Mostly just fixing some of the filed issues, and merging some PR code. The upstream project is non-maintained and can be considered dead. For my own sake, I removed some of the gopkg branch anchors to reduce complexity.
Introduction
statsd is a simple and efficient Statsd client.
Features
- Supports all StatsD metrics: counter, gauge, timing and set
- Supports InfluxDB and Datadog tags
- Fast and GC-friendly: all functions for sending metrics do not allocate
- Efficient: metrics are buffered by default
- Simple and clean API
- No 3rd-party dependencies
- An annoying hyphen in the name
- Options for lazy connection and regular DNS/connection re-resolving
Usage
The basic usage can be very simple, see example_test. The documentation illustrates the more complex API methods and options.
Documentation
https://godoc.org/github.com/AstromechZA/go-statsd
Download
$ go get github.com/AstromechZA/go-statsd
License
Documentation
¶
Overview ¶
Package statsd is a simple and efficient StatsD client.
Options ¶
Use options to configure the Client: target host/port, sampling rate, tags, etc.
Whenever you want to use different options (e.g. other tags, different sampling rate), you should use the Clone() method of the Client.
Because when cloning a Client, the same connection is reused so this is way cheaper and more efficient than creating another Client using New().
Internals ¶
Client's methods buffer metrics. The buffer is flushed when either:
- the background goroutine flushes the buffer (every 100ms by default)
- the buffer is full (1440 bytes by default so that IP packets are not fragmented)
The background goroutine can be disabled using the FlushPeriod(0) option.
Buffering can be disabled using the MaxPacketSize(0) option.
StatsD homepage: https://github.com/etsy/statsd
Example ¶
client, err := statsd.New(statsd.Address("127.0.0.1:8125"))
if err != nil {
panic(err)
}
defer client.Close()
client.Increment("thing.counter")
client.Gauge("value.dial", 42.3)
Output:
Index ¶
- Constants
- type Client
- func (c *Client) Clone(opts ...Option) *Client
- func (c *Client) Close()
- func (c *Client) Count(bucket string, n interface{})
- func (c *Client) Flush()
- func (c *Client) Gauge(bucket string, value interface{})
- func (c *Client) Histogram(bucket string, value interface{})
- func (c *Client) Increment(bucket string)
- func (c *Client) NewTiming() Timing
- func (c *Client) Timing(bucket string, value interface{})
- func (c *Client) Unique(bucket string, value string)
- type Option
- func Address(addr string) Option
- func ErrorHandler(h func(error)) Option
- func FlushPeriod(p time.Duration) Option
- func FlushesBetweenReconnect(n int) Option
- func LazyConnect() Option
- func MaxPacketSize(n int) Option
- func Mute(b bool) Option
- func Network(network string) Option
- func Prefix(p string) Option
- func SampleRate(rate float32) Option
- func Tags(tags ...string) Option
- func TagsFormat(tf TagFormat) Option
- type TagFormat
- type Timing
Examples ¶
Constants ¶
const DefaultAddress = "localhost:8125"
DefaultAddress is the default statsd receiver
const DefaultFlashPeriod = 100 * time.Millisecond
DefaultFlashPeriod is how often the buffer is flushed
const DefaultMaxPackageSize = 1500 - 40 - 20
DefaultMaxPackageSize must match the network MTU : Ethernet MTU - IPv6 Header - TCP Header
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
A Client represents a StatsD client.
func (*Client) Clone ¶
Clone returns a clone of the Client. The cloned Client inherits its configuration from its parent.
All cloned Clients share the same connection, so cloning a Client is a cheap operation.
func (*Client) Close ¶
func (c *Client) Close()
Close flushes the Client's buffer and releases the associated ressources. The Client and all the cloned Clients must not be used afterward.
func (*Client) Increment ¶
Increment increment the given bucket. It is equivalent to Count(bucket, 1).
type Option ¶
type Option func(*config)
An Option represents an option for a Client. It must be used as an argument to New() or Client.Clone().
func Address ¶
Address sets the address of the StatsD daemon.
By default, "localhost:8125" is used. This option is ignored in Client.Clone().
func ErrorHandler ¶
ErrorHandler sets the function called when an error happens when sending metrics (e.g. the StatsD daemon is not listening anymore).
By default, these errors are ignored. This option is ignored in Client.Clone().
func FlushPeriod ¶
FlushPeriod sets how often the Client's buffer is flushed. If p is 0, the goroutine that periodically flush the buffer is not lauched and the buffer is only flushed when it is full.
By default, the flush period is 100 ms. This option is ignored in Client.Clone().
func FlushesBetweenReconnect ¶
FlushesBetweenReconnect allows the connection to be torn down after N flush periods.
This is very useful in environments where the statsd server can move around, go up and down, or in general be unstable. You don't want that to prevent your service from sending metrics for the rest of time.
func LazyConnect ¶
func LazyConnect() Option
LazyConnect allows the connection to be made only at flush time
This can be useful to avoid unecessary errors at initialisation time if the statsd server is not up or cannot be resolved.
func MaxPacketSize ¶
MaxPacketSize sets the maximum packet size in bytes sent by the Client.
By default, it is 1440 to avoid IP fragmentation. This option is ignored in Client.Clone().
func Mute ¶
Mute sets whether the Client is muted. All methods of a muted Client do nothing and return immedialtly.
This option can be used in Client.Clone() only if the parent Client is not muted. The clones of a muted Client are always muted.
func Network ¶
Network sets the network (udp, tcp, etc) used by the client. See the net.Dial documentation (https://golang.org/pkg/net/#Dial) for the available network options.
By default, network is udp. This option is ignored in Client.Clone().
func Prefix ¶
Prefix appends the prefix that will be used in every bucket name.
Note that when used in cloned, the prefix of the parent Client is not replaced but is prepended to the given prefix.
func SampleRate ¶
SampleRate sets the sample rate of the Client. It allows sending the metrics less often which can be useful for performance intensive code paths.
func Tags ¶
Tags appends the given tags to the tags sent with every metrics. If a tag already exists, it is replaced.
The tags must be set as key-value pairs. If the number of tags is not even, Tags panics.
If the format of tags have not been set using the TagsFormat option, the tags will be ignored.
type TagFormat ¶
type TagFormat uint8
TagFormat represents the format of tags sent by a Client.
const ( // InfluxDB tag format. // See https://influxdb.com/blog/2015/11/03/getting_started_with_influx_statsd.html InfluxDB TagFormat = iota + 1 // Datadog tag format. // See http://docs.datadoghq.com/guides/metrics/#tags Datadog )
Source Files