statsd is a simple yet powerful, futuristic StatsD client written in Go.
- Best suitable for netdata
- Supports Counting, Sampling, Timing, Gauges, Sets and Histograms out of the box
- Futuristic and Extendable: Ability to send custom metric values and types, yet unknown to the current client
- It is blazing fast and it does not allocate unnecessary memory. Metrics are sent based on a customized packet size, manual
Flushingof buffered metrics is also an option - Beautiful and easy to learn API
- Easy for testing, the
NewClientfunction accepts anio.WriteCloser, so you use it to test the sent metrics of your application on a development environment - Protocol-unawareness.
The only requirement is the Go Programming Language
$ go get -u github.com/netdata/statsdI know your time is valuable, so just bear with me another minute.
statsd is simple, it won't take more than 10 minutes of your time to read all of its documentation via godocs.
// NewClient returns a new StatsD client.
// The first input argument, "writeCloser", should be a value which completes the
// `io.WriteCloser` interface
// It can be a UDP connection or a string buffer or even the stdout for testing.
// The second input argument, "prefix" can be empty
// but it is usually the app's name and a single dot.
NewClient(writeCloser io.WriteCloser, prefix string) *ClientClient {
SetMaxPackageSize(maxPacketSize int)
SetFormatter(fmt func(metricName string) string)
FlushEvery(dur time.Duration)
IsClosed() bool
Close() error
WriteMetric(metricName, value, typ string, rate float32) error
Flush(n int) error
Count(metricName string, value int) error
Increment(metricName string) error
Gauge(metricName string, value int) error
Unique(metricName string, value int) error
Time(metricName string, value time.Duration) error
Record(metricName string, rate float32) func() error
}Duration(v time.Duration) string
Int(v int) string
Int8(v int8) string
Int16(v int16) string
Int32(v int32) string
Int64(v int64) string
Uint(v uint) string
Uint8(v uint8) string
Uint16(v uint16) string
Uint32(v uint32) string
Uint64(v uint64) string
Float32(v float32) string
Float64(v float64) stringconst (
// Count is the "c" Counting statsd metric type.
Count string = "c"
// Gauge is the "g" Gauges statsd metric type.
Gauge string = "g"
// Unique is the "s" Sets statsd metric type.
Unique string = "s"
// Set is an alias for "Unique"
Set = Unique
// Time is the "ms" Timing statsd metric type.
Time string = "ms"
// Histogram is the "h" metric type,
// difference from `Time` metric type is that `Time` writes milleseconds.
// Read more at: https://docs.netdata.cloud/collectors/statsd.plugin/
Histogram string = "h"
)Read more at: https://github.com/etsy/statsd/blob/master/docs/metric_types.md
Assuming that you have a statsd server running at :8125 (default port).
# assume the following codes in example.go file
$ cat example.gopackage main
import (
"fmt"
"net/http"
"strings"
"time"
"github.com/netdata/statsd"
)
// statusCodeReporter is a compatible `http.ResponseWriter`
// which stores the `statusCode` for further reporting.
type statusCodeReporter struct {
http.ResponseWriter
written bool
statusCode int
}
func (w *statusCodeReporter) WriteHeader(statusCode int) {
if w.written {
return
}
w.statusCode = statusCode
w.ResponseWriter.WriteHeader(statusCode)
}
func (w *statusCodeReporter) Write(b []byte) (int, error) {
w.written = true
return w.ResponseWriter.Write(b)
}
func main() {
statsWriter, err := statsd.UDP(":8125")
if err != nil {
panic(err)
}
statsD := statsd.NewClient(statsWriter, "prefix.")
statsD.FlushEvery(5 * time.Second)
statsDMiddleware := func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
path := r.URL.Path
if len(path) == 1 {
path = "index" // for root.
} else if path == "/favicon.ico" {
next.ServeHTTP(w, r)
return
} else {
path = path[1:]
path = strings.Replace(path, "/", ".", -1)
}
// HERE
statsD.Increment(fmt.Sprintf("%s.request", path))
newResponseWriter := &statusCodeReporter{ResponseWriter: w, statusCode: http.StatusOK}
// HERE
stop := statsD.Record(fmt.Sprintf("%s.time", path), 1)
next.ServeHTTP(newResponseWriter, r)
stop()
// HERE
statsD.Increment(fmt.Sprintf("%s.response.%d", path, newResponseWriter.statusCode))
})
}
mux := http.DefaultServeMux
mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintln(w, "Hello from index")
})
mux.HandleFunc("/other", func(w http.ResponseWriter, r *http.Request) {
// HERE
statsD.Unique("other.unique", 1)
fmt.Fprintln(w, "Hello from other page")
})
http.ListenAndServe(":8080", statsDMiddleware(mux))
}# run example.go and visit http://localhost:8080/other
$ go run example.go
Navigate here to discover all available examples.
StatsD Go Client is licensed under the GNU GENERAL PUBLIC License.