The highest tagged major version is
README
¶
statsd
Statsd Go client library
This project has been originally forked and extended from https://github.com/alexcesaro/statsd
This package is a simple and efficient StatsD client. StatsD is a network daemon that listens for statistics and aggregates them to one or more pluggable backend services (e.g., Graphite). For more information about StatsD, visit the StatsD homepage: https://github.com/etsy/statsd
The packages documentation is available at: https://pkg.golang.ir/github.com/tecnickcom/statsd
- category Library
- license MIT
- link https://github.com/tecnickcom/statsd
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
- 100% test coverage
Developers' Quick Start
To quickly get started with this project, follow these steps:
- Ensure you have installed the latest Go version.
- Clone the repository:
git clone https://github.com/tecnickcom/statsd.git. - Change into the project directory:
cd statsd. - Install the required dependencies and test everything:
DEVMODE=LOCAL make x.
Now you are ready to start developing with statsd!
This project includes a Makefile that allows you to test and build the project in a Linux-compatible system with simple commands.
All the artifacts and reports produced using this Makefile are stored in the target folder.
Alternatively, everything can be built inside a Docker container using the command make dbuild that uses the environment defined at resources/docker/Dockerfile.dev.
To see all available options:
make help
Running all tests
Before committing the code, please format it and check if it passes all tests using
DEVMODE=LOCAL make x
Example
c, err := statsd.New() // Connect to the UDP port 8125 by default.
if err != nil {
// If nothing is listening on the target port, an error is returned and
// the returned client does nothing but is still usable. So we can
// just log the error and go on.
log.Print(err)
}
defer c.Close()
// Increment a counter.
c.Increment("foo.counter")
// Gauge something.
c.Gauge("num_goroutine", runtime.NumGoroutine())
// Time something.
t := c.NewTiming()
ping("http://example.com/")
t.Send("homepage.response_time")
// It can also be used as a one-liner to easily time a function.
pingHomepage := func() {
defer c.NewTiming().Send("homepage.response_time")
ping("http://example.com/")
}
pingHomepage()
// Cloning a Client allows using different parameters while still using the
// same connection.
// This is way cheaper and more efficient than using New().
stat := c.Clone(statsd.Prefix("http"), statsd.SampleRate(0.2))
stat.Increment("view") // Increments http.view
Documentation
¶
Overview ¶
Package statsd is a simple and efficient StatsD client.
StatsD is a network daemon that listens for statistics and aggregates them to one or more pluggable backend services (e.g., Graphite).
The statsd package provides options to configure the client, such as the target host/port, sampling rate, and tags. To use different options, you can clone the client using the Clone() method.
The client's methods buffer metrics, and the buffer is flushed either by the background goroutine (every 100ms by default) or when the buffer is full (1440 bytes by default to avoid IP packet fragmentation). You can disable the background goroutine using the FlushPeriod(0) option and disable buffering using the MaxPacketSize(0) option.
For more information about StatsD, visit the StatsD homepage: https://github.com/etsy/statsd
Example ¶
package main
import (
"log"
"runtime"
"github.com/tecnickcom/statsd"
)
func ping(_ string) {}
func main() {
c, err := statsd.New() // Connect to the UDP port 8125 by default.
if err != nil {
// If nothing is listening on the target port, an error is returned and
// the returned client does nothing but is still usable. So we can
// just log the error and go on.
log.Print(err)
}
defer c.Close()
// Increment a counter.
c.Increment("foo.counter")
// Gauge something.
c.Gauge("num_goroutine", runtime.NumGoroutine())
// Time something.
t := c.NewTiming()
ping("http://example.com/")
t.Send("homepage.response_time")
// It can also be used as a one-liner to easily time a function.
pingHomepage := func() {
defer c.NewTiming().Send("homepage.response_time")
ping("http://example.com/")
}
pingHomepage()
// Cloning a Client allows using different parameters while still using the
// same connection.
// This is way cheaper and more efficient than using New().
stat := c.Clone(statsd.Prefix("http"), statsd.SampleRate(0.2))
stat.Increment("view") // Increments http.view
}
Output:
Index ¶
- 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 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 ¶
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 (*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.
Example ¶
package main
import (
"log"
"github.com/tecnickcom/statsd"
)
func main() {
c, err := statsd.New(statsd.Prefix("my_app"))
if err != nil {
log.Print(err)
}
httpStats := c.Clone(statsd.Prefix("http"))
httpStats.Increment("foo.bar") // Increments: my_app.http.foo.bar
}
Output:
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).
func (*Client) NewTiming ¶
NewTiming creates a new Timing.
Example ¶
package main
import (
"log"
"github.com/tecnickcom/statsd"
)
func ping(_ string) {}
func main() {
c, err := statsd.New()
if err != nil {
log.Print(err)
}
// Send a timing metric each time the function is run.
defer c.NewTiming().Send("homepage.response_time")
ping("http://example.com/")
}
Output:
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, ":8125" is used. This option is ignored in Client.Clone().
Example ¶
package main
import (
"log"
"github.com/tecnickcom/statsd"
)
func main() {
_, err := statsd.New(statsd.Address("192.168.0.5:8126"))
if err != nil {
log.Print(err)
}
}
Output:
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().
Example ¶
package main
import (
"log"
"github.com/tecnickcom/statsd"
)
func main() {
_, err := statsd.New(statsd.ErrorHandler(func(err error) {
log.Print(err)
}))
if err != nil {
log.Print(err)
}
}
Output:
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().
Example ¶
package main
import (
"log"
"time"
"github.com/tecnickcom/statsd"
)
func main() {
_, err := statsd.New(statsd.FlushPeriod(10 * time.Millisecond))
if err != nil {
log.Print(err)
}
}
Output:
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().
Example ¶
package main
import (
"log"
"github.com/tecnickcom/statsd"
)
func main() {
_, err := statsd.New(statsd.MaxPacketSize(512))
if err != nil {
log.Print(err)
}
}
Output:
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.
Example ¶
package main
import (
"log"
"github.com/tecnickcom/statsd"
)
func main() {
c, err := statsd.New(statsd.Mute(true))
if err != nil {
log.Print(err)
}
c.Increment("foo.bar") // Does nothing.
}
Output:
func Network ¶
Network sets the network (udp, tcp, etc) used by the client. See the net.Dial documentation (https://golang.ir/pkg/net/#Dial) for the available network options.
By default, network is udp. This option is ignored in Client.Clone().
Example ¶
package main
import (
"log"
"github.com/tecnickcom/statsd"
)
func main() {
// Send metrics using a TCP connection.
_, err := statsd.New(statsd.Network("tcp"))
if err != nil {
log.Print(err)
}
}
Output:
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.
Example ¶
package main
import (
"log"
"github.com/tecnickcom/statsd"
)
func main() {
c, err := statsd.New(statsd.Prefix("my_app"))
if err != nil {
log.Print(err)
}
c.Increment("foo.bar") // Increments: my_app.foo.bar
}
Output:
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.
Example ¶
package main
import (
"log"
"github.com/tecnickcom/statsd"
)
func main() {
_, err := statsd.New(statsd.SampleRate(0.2)) // Send metrics 20% of the time.
if err != nil {
log.Print(err)
}
}
Output:
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.
Example ¶
package main
import (
"log"
"github.com/tecnickcom/statsd"
)
func main() {
_, err := statsd.New(
statsd.TagsFormat(statsd.InfluxDB),
statsd.Tags("region", "us", "app", "my_app"),
)
if err != nil {
log.Print(err)
}
}
Output:
func TagsFormat ¶
TagsFormat sets the format of tags.
Example ¶
package main
import (
"log"
"github.com/tecnickcom/statsd"
)
func main() {
_, err := statsd.New(statsd.TagsFormat(statsd.InfluxDB))
if err != nil {
log.Print(err)
}
}
Output:
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