https://github.com/rs/xstats
xstats is a generic client for service instrumentation
https://github.com/rs/xstats
Last synced: 8 months ago
JSON representation
xstats is a generic client for service instrumentation
- Host: GitHub
- URL: https://github.com/rs/xstats
- Owner: rs
- License: mit
- Created: 2015-10-23T09:03:33.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2020-08-04T04:02:28.000Z (almost 6 years ago)
- Last Synced: 2025-03-27T20:06:50.960Z (about 1 year ago)
- Language: Go
- Homepage:
- Size: 49.8 KB
- Stars: 82
- Watchers: 4
- Forks: 16
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# XStats
[](https://godoc.org/github.com/rs/xstats) [](https://raw.githubusercontent.com/rs/xstats/master/LICENSE) [](https://travis-ci.org/rs/xstats) [](http://gocover.io/github.com/rs/xstats)
Package `xstats` is a generic client for service instrumentation.
`xstats` is inspired from Go-kit's [metrics](https://github.com/go-kit/kit/tree/master/metrics) package but it takes a slightly different path. Instead of having to create an instance for each metric, `xstats` use a single instance to log every metrics you want. This reduces the boiler plate when you have a lot a metrics in your app. It's also easier in term of dependency injection.
Talking about dependency injection, `xstats` comes with a [xhandler.Handler](https://github.com/rs/xhandler) integration so it can automatically inject the `xstats` client within the `net/context` of each request. Each request's `xstats` instance have its own tags storage ; This let you inject some per request contextual tags to be included with all observations sent within the lifespan of the request.
`xstats` is pluggable and comes with integration for `expvar`, `StatsD` and `DogStatsD`, the [Datadog](http://datadoghq.com) augmented version of StatsD with support for tags. More integration may come later (PR welcome).
## Supported Clients
- [StatsD](https://github.com/b/statsd_spec)
- [DogStatsD](http://docs.datadoghq.com/guides/dogstatsd/#datagram-format)
- [expvar](https://golang.org/pkg/expvar/)
- [prometheus](https://github.com/prometheus/client_golang)
- [telegraf](https://influxdata.com/blog/getting-started-with-sending-statsd-metrics-to-telegraf-influxdb)
- [mock](https://github.com/stretchr/testify)
## Install
go get github.com/rs/xstats
## Usage
```go
// Defines interval between flushes to statsd server
flushInterval := 5 * time.Second
// Connection to the statsd server
statsdWriter, err := net.Dial("udp", "127.0.0.1:8126")
if err != nil {
log.Fatal(err)
}
// Create the stats client
s := xstats.New(dogstatsd.New(statsdWriter, flushInterval))
// Global tags sent with all metrics (only with supported clients like datadog's)
s.AddTags("role:my-service", "dc:sv6")
// Send some observations
s.Count("requests", 1, "tag")
s.Timing("something", 5*time.Millisecond, "tag")
```
Integration with [github.com/rs/xhandler](https://github.com/rs/xhandler):
```go
var xh xhandler.HandlerC
// Here is your handler
xh = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// Get the xstats request's instance from the context. You can safely assume it will
// be always there, if the handler is removed, xstats.FromContext will return a nop
// instance.
m := xstats.FromRequest(r)
// Count something
m.Count("requests", 1, "route:index")
})
// Install the metric handler with dogstatsd backend client and some env tags
flushInterval := 5 * time.Second
tags := []string{"role:my-service"}
statsdWriter, err := net.Dial("udp", "127.0.0.1:8126")
if err != nil {
log.Fatal(err)
}
xh = xstats.NewHandler(dogstatsd.New(statsdWriter, flushInterval), tags, xh)
// Root context
ctx := context.Background()
h := xhandler.New(ctx, xh)
http.Handle("/", h)
if err := http.ListenAndServe(":8080", nil); err != nil {
log.Fatal(err)
}
```
## Testing
```go
func TestFunc(t *testing.T) {
m := mock.New()
s := xstats.New(m)
m.On("Timing", "something", 5*time.Millisecond, "tag")
s.Timing("something", 5*time.Millisecond, "tag")
s.AssertExpectations(t)
}
```
## Licenses
All source code is licensed under the [MIT License](https://raw.github.com/rs/xstats/master/LICENSE).