{"id":15372988,"url":"https://github.com/rs/xstats","last_synced_at":"2025-09-09T13:37:01.699Z","repository":{"id":57481141,"uuid":"44802349","full_name":"rs/xstats","owner":"rs","description":"xstats is a generic client for service instrumentation","archived":false,"fork":false,"pushed_at":"2020-08-04T04:02:28.000Z","size":51,"stargazers_count":82,"open_issues_count":5,"forks_count":16,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-27T20:06:50.960Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-10-23T09:03:33.000Z","updated_at":"2024-12-09T04:14:14.000Z","dependencies_parsed_at":"2022-09-26T17:50:38.612Z","dependency_job_id":null,"html_url":"https://github.com/rs/xstats","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rs%2Fxstats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rs%2Fxstats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rs%2Fxstats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rs%2Fxstats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rs","download_url":"https://codeload.github.com/rs/xstats/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248830881,"owners_count":21168360,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-01T13:53:53.467Z","updated_at":"2025-04-14T06:21:21.004Z","avatar_url":"https://github.com/rs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# XStats\n\n[![godoc](http://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://godoc.org/github.com/rs/xstats) [![license](http://img.shields.io/badge/license-MIT-red.svg?style=flat)](https://raw.githubusercontent.com/rs/xstats/master/LICENSE) [![Build Status](https://travis-ci.org/rs/xstats.svg?branch=master)](https://travis-ci.org/rs/xstats) [![Coverage](http://gocover.io/_badge/github.com/rs/xstats)](http://gocover.io/github.com/rs/xstats)\n\nPackage `xstats` is a generic client for service instrumentation.\n\n`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.\n\nTalking 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.\n\n`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).\n\n## Supported Clients\n\n- [StatsD](https://github.com/b/statsd_spec)\n- [DogStatsD](http://docs.datadoghq.com/guides/dogstatsd/#datagram-format)\n- [expvar](https://golang.org/pkg/expvar/)\n- [prometheus](https://github.com/prometheus/client_golang)\n- [telegraf](https://influxdata.com/blog/getting-started-with-sending-statsd-metrics-to-telegraf-influxdb)\n- [mock](https://github.com/stretchr/testify)\n\n## Install\n\n    go get github.com/rs/xstats\n\n## Usage\n\n```go\n// Defines interval between flushes to statsd server\nflushInterval := 5 * time.Second\n\n// Connection to the statsd server\nstatsdWriter, err := net.Dial(\"udp\", \"127.0.0.1:8126\")\nif err != nil {\n    log.Fatal(err)\n}\n\n// Create the stats client\ns := xstats.New(dogstatsd.New(statsdWriter, flushInterval))\n\n// Global tags sent with all metrics (only with supported clients like datadog's)\ns.AddTags(\"role:my-service\", \"dc:sv6\")\n\n// Send some observations\ns.Count(\"requests\", 1, \"tag\")\ns.Timing(\"something\", 5*time.Millisecond, \"tag\")\n```\n\nIntegration with [github.com/rs/xhandler](https://github.com/rs/xhandler):\n\n```go\nvar xh xhandler.HandlerC\n\n// Here is your handler\nxh = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n    // Get the xstats request's instance from the context. You can safely assume it will\n    // be always there, if the handler is removed, xstats.FromContext will return a nop\n    // instance.\n    m := xstats.FromRequest(r)\n\n    // Count something\n    m.Count(\"requests\", 1, \"route:index\")\n})\n\n// Install the metric handler with dogstatsd backend client and some env tags\nflushInterval := 5 * time.Second\ntags := []string{\"role:my-service\"}\nstatsdWriter, err := net.Dial(\"udp\", \"127.0.0.1:8126\")\nif err != nil {\n    log.Fatal(err)\n}\nxh = xstats.NewHandler(dogstatsd.New(statsdWriter, flushInterval), tags, xh)\n\n// Root context\nctx := context.Background()\nh := xhandler.New(ctx, xh)\nhttp.Handle(\"/\", h)\n\nif err := http.ListenAndServe(\":8080\", nil); err != nil {\n    log.Fatal(err)\n}\n```\n\n## Testing\n```go\nfunc TestFunc(t *testing.T) {\n    m := mock.New()\n    s := xstats.New(m)\n    m.On(\"Timing\", \"something\", 5*time.Millisecond, \"tag\")\n    s.Timing(\"something\", 5*time.Millisecond, \"tag\")\n    s.AssertExpectations(t)\n}\n```\n\n## Licenses\n\nAll source code is licensed under the [MIT License](https://raw.github.com/rs/xstats/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frs%2Fxstats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frs%2Fxstats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frs%2Fxstats/lists"}