The highest tagged major version is
README
¶
statsd
Introduction
statsd is a simple and efficient Statsd client.
See the benchmark for a comparison with other Go StatsD clients.
Features
- Supports all StatsD metrics: counter, gauge, timing and set
- Supports Datadog and InfluxDB tags
- Fast and GC-friendly: Client's methods do not allocate
- Simple API
- 100% test coverage
- Versioned API using gopkg.in
Documentation
https://godoc.org/gopkg.in/alexcesaro/statsd.v1
Download
go get gopkg.in/alexcesaro/statsd.v1
Example
See the examples in the documentation.
License
Contribute
Do you have any question the documentation does not answer? Is there a use case that you feel is common and is not well-addressed by the current API?
If so you are more than welcome to ask questions in the thread on golang-nuts or open an issue or send a pull-request here on Github.
Documentation
¶
Overview ¶
Package statsd is a simple and efficient StatsD client.
Client's methods are fast and do not allocate memory.
Internally, Client's methods buffers 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 WithFlushPeriod(0) option.
Buffering can be disabled using the WithMaxPacketSize(0) option.
StatsD homepage: https://github.com/etsy/statsd
Example ¶
package main
import (
"net/http"
"runtime"
"github.com/alexcesaro/statsd"
)
func main() {
c, err := statsd.New(":8125")
if err != nil {
panic(err)
}
c.Increment("foo.counter")
c.Gauge("num_goroutine", runtime.NumGoroutine())
t := c.NewTiming()
http.Get("http://example.com/")
t.Send("homepage.response_time", 1)
// Can also be used as a one-liner in a function:
// func PingHomepage() {
// defer c.NewTiming().Send("homepage.response_time", 1)
// http.Get("http://example.com/")
// }
c.Close()
}
Output:
Index ¶
- type Client
- func (c *Client) ChangeGauge(bucket string, delta int)
- func (c *Client) Close()
- func (c *Client) Count(bucket string, n int, rate float32)
- func (c *Client) Flush()
- func (c *Client) Gauge(bucket string, value int)
- func (c *Client) Increment(bucket string)
- func (c *Client) NewTiming() Timing
- func (c *Client) Timing(bucket string, value int, rate float32)
- func (c *Client) Unique(bucket string, value string)
- type Option
- func Mute(b bool) Option
- func WithDatadogTags(tags ...string) Option
- func WithErrorHandler(h func(error)) Option
- func WithFlushPeriod(period time.Duration) Option
- func WithInfluxDBTags(tags ...string) Option
- func WithMaxPacketSize(n int) Option
- func WithNetwork(network string) Option
- func WithPrefix(prefix string) Option
- type Timing
Examples ¶
Constants ¶
This section is empty.
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 New ¶
New returns a new Client with the given options. It returns an error only if there is a network error. In this case, it returns a muted client along with the error.
func (*Client) ChangeGauge ¶
ChangeGauge changes the value of a gauge by the given delta.
func (*Client) Close ¶
func (c *Client) Close()
Close flushes the Client's buffer and releases the associated ressources.
func (*Client) Increment ¶
Increment increment the given bucket. It is equivalent to Count(bucket, 1, 1).
func (*Client) NewTiming ¶
NewTiming creates a new Timing.
Example ¶
package main
import (
"net/http"
"github.com/alexcesaro/statsd"
)
var c *statsd.Client
func main() {
// Send a timing metric each time the function is run.
defer c.NewTiming().Send("homepage.response_time", 1)
http.Get("http://example.com/")
}
Output:
type Option ¶
type Option func(*Client)
An Option represents an option for a Client. It must be used as an argument to New().
func Mute ¶
Mute sets whether the Client is muted.
Example ¶
package main
import (
"github.com/alexcesaro/statsd"
)
func main() {
c, err := statsd.New(":8125", statsd.Mute(true))
if err != nil {
panic(err)
}
c.Increment("foo.bar") // Does nothing.
}
Output:
func WithDatadogTags ¶
WithDatadogTags sets the Datadog tags sent with every metrics.
The tags should have the key:value syntax. See http://docs.datadoghq.com/guides/metrics/#tags
Example ¶
package main
import (
"github.com/alexcesaro/statsd"
)
func main() {
statsd.New(":8125", statsd.WithDatadogTags("region:us", "app:my_app"))
}
Output:
func WithErrorHandler ¶
WithErrorHandler sets the error handling function used by the Client.
Example ¶
package main
import (
"log"
"github.com/alexcesaro/statsd"
)
func main() {
statsd.New(":8125", statsd.WithErrorHandler(func(err error) {
log.Print(err)
}))
}
Output:
func WithFlushPeriod ¶
WithFlushPeriod sets how often the Client's buffer is flushed. If period 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 milliseconds.
Example ¶
package main
import (
"time"
"github.com/alexcesaro/statsd"
)
func main() {
statsd.New(":8125", statsd.WithFlushPeriod(10*time.Millisecond))
}
Output:
func WithInfluxDBTags ¶
WithInfluxDBTags sets the InfluxDB tags sent with every metrics.
The tags must be set as key-value pairs. If the number of tags is not even, WithInfluxDBTags panics.
See https://influxdb.com/blog/2015/11/03/getting_started_with_influx_statsd.html
Example ¶
package main
import (
"github.com/alexcesaro/statsd"
)
func main() {
statsd.New(":8125", statsd.WithInfluxDBTags("region", "us", "app", "my_app"))
}
Output:
func WithMaxPacketSize ¶
WithMaxPacketSize sets the maximum packet size in bytes sent by the Client.
By default it is 1440.
Example ¶
package main
import (
"github.com/alexcesaro/statsd"
)
func main() {
statsd.New(":8125", statsd.WithMaxPacketSize(512))
}
Output:
func WithNetwork ¶
WithNetwork sets the network (udp, tcp, etc) used by the client. See net.Dial documentation: https://golang.org/pkg/net/#Dial
By default, network is udp.
Example ¶
package main
import (
"github.com/alexcesaro/statsd"
)
func main() {
// Send metrics using a TCP connection.
statsd.New(":8125", statsd.WithNetwork("tcp"))
}
Output:
func WithPrefix ¶
WithPrefix sets the prefix prepended to every bucket name.
Example ¶
package main
import (
"github.com/alexcesaro/statsd"
)
func main() {
c, err := statsd.New(":8125", statsd.WithPrefix("my_app."))
if err != nil {
panic(err)
}
c.Increment("foo.bar") // Increments "my_app.foo.bar".
}
Output:
Source Files