{"id":16769245,"url":"https://github.com/smira/go-statsd","last_synced_at":"2025-05-15T13:05:14.001Z","repository":{"id":54556839,"uuid":"115451469","full_name":"smira/go-statsd","owner":"smira","description":"Go statsd client library with zero allocation overhead, great performance and reconnects","archived":false,"fork":false,"pushed_at":"2024-10-29T11:20:41.000Z","size":43,"stargazers_count":113,"open_issues_count":6,"forks_count":18,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-15T02:11:51.369Z","etag":null,"topics":["golang","monitoring","statsd","statsite","zero-allocation"],"latest_commit_sha":null,"homepage":null,"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/smira.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-26T20:05:14.000Z","updated_at":"2025-03-03T13:19:19.000Z","dependencies_parsed_at":"2024-06-18T13:47:59.213Z","dependency_job_id":"4c483c4d-7a99-4026-97d9-ed4529c24fd7","html_url":"https://github.com/smira/go-statsd","commit_stats":{"total_commits":28,"total_committers":9,"mean_commits":3.111111111111111,"dds":0.3928571428571429,"last_synced_commit":"cee3b7c031bcb785a7217e9f98fc810aee82ec9d"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smira%2Fgo-statsd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smira%2Fgo-statsd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smira%2Fgo-statsd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smira%2Fgo-statsd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smira","download_url":"https://codeload.github.com/smira/go-statsd/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254346624,"owners_count":22055808,"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":["golang","monitoring","statsd","statsite","zero-allocation"],"created_at":"2024-10-13T06:13:40.339Z","updated_at":"2025-05-15T13:05:13.965Z","avatar_url":"https://github.com/smira.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/smira/go-statsd.svg?branch=master)](https://travis-ci.org/smira/go-statsd)\n[![Documentation](https://godoc.org/github.com/smira/go-statsd?status.svg)](http://godoc.org/github.com/smira/go-statsd)\n[![Go Report Card](https://goreportcard.com/badge/github.com/smira/go-statsd)](https://goreportcard.com/report/github.com/smira/go-statsd)\n[![codecov](https://codecov.io/gh/smira/go-statsd/branch/master/graph/badge.svg)](https://codecov.io/gh/smira/go-statsd)\n[![License](https://img.shields.io/github/license/smira/go-statsd.svg?maxAge=2592000)](https://github.com/smira/go-statsd/LICENSE)\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fsmira%2Fgo-statsd.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fsmira%2Fgo-statsd?ref=badge_shield)\n\nGo statsd client library with zero allocation overhead, great performance and automatic\nreconnects.\n\nClient has zero memory allocation per metric sent:\n\n* ring of buffers, each buffer is UDP packet\n* buffer is taken from the pool, filled with metrics, passed on to the network delivery and\nreturned to the pool\n* buffer is flushed either when it is full or when flush period comes (e.g. every 100ms)\n* separate goroutines handle network operations: sending UDP packets and reconnecting UDP socket\n* when metric is serialized, zero allocation operations are used to avoid `reflect` and temporary buffers\n\n## Zero memory allocation\n\nAs metrics could be sent by the application at very high rate (e.g. hundreds of metrics per one request),\nit is important that sending metrics doesn't cause any additional GC or CPU pressure. `go-statsd` is using\nbuffer pools and it tries to avoid allocations while building statsd packets.\n\n## Reconnecting to statsd\n\nWith modern container-based platforms with dynamic DNS statsd server might change its address when container\ngets rescheduled. As statsd packets are delivered over UDP, there's no easy way for the client to figure out\nthat packets are going nowhere. `go-statsd` supports configurable reconnect interval which forces DNS resolution.\n\nWhile client is reconnecting, metrics are still processed and buffered.\n\n## Dropping metrics\n\nWhen buffer pool is exhausted, `go-statsd` starts dropping packets. Number of dropped packets is reported via\n`Client.GetLostPackets()` and every minute logged using `log.Printf()`. Usually packets should never be dropped,\nif that happens it's usually signal of enormous metric volume.\n\n## Stastd server\n\nAny statsd-compatible server should work well with `go-statsd`, [statsite](https://github.com/statsite/statsite) works\nexceptionally well as it has great performance and low memory footprint even with huge number of metrics.\n\n## Usage\n\nInitialize client instance with options, one client per application is usually enough:\n\n```go\nclient := statsd.NewClient(\"localhost:8125\",\n    statsd.MaxPacketSize(1400),\n    statsd.MetricPrefix(\"web.\"))\n```\n\nSend metrics as events happen in the application, metrics will be packed together and\ndelivered to statsd server:\n\n```go\nstart := time.Now()\nclient.Incr(\"requests.http\", 1)\n// ...\nclient.PrecisionTiming(\"requests.route.api.latency\", time.Since(start))\n```\n\nShutdown client during application shutdown to flush all the pending metrics:\n\n```go\nclient.Close()\n```\n\n## Tagging\n\nMetrics could be tagged to support aggregation on TSDB side. go-statsd supports\ntags in [InfluxDB](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/statsd)\n, [Datadog](https://docs.datadoghq.com/developers/dogstatsd/#datagram-format)\nand [Graphite](https://graphite.readthedocs.io/en/latest/tags.html) formats.\nFormat and default tags (applied to every metric) are passed as options\nto the client initialization:\n\n```go\nclient := statsd.NewClient(\"localhost:8125\",\n    statsd.TagStyle(TagFormatDatadog),\n    statsd.DefaultTags(statsd.StringTag(\"app\", \"billing\")))\n```\n\nFor every metric sent, tags could be added as the last argument(s) to the function\ncall:\n\n```go\nclient.Incr(\"request\", 1,\n    statsd.StringTag(\"procotol\", \"http\"), statsd.IntTag(\"port\", 80))\n```\n\n\n## Benchmark\n\n[Benchmark](https://github.com/smira/go-statsd-benchmark) comparing several clients:\n\n* https://github.com/alexcesaro/statsd/ (`Alexcesaro`)\n* this client (`GoStatsd`)\n* https://github.com/cactus/go-statsd-client (`Cactus`)\n* https://github.com/peterbourgon/g2s (`G2s`)\n* https://github.com/quipo/statsd (`Quipo`)\n* https://github.com/Unix4ever/statsd (`Unix4ever`)\n\nBenchmark results:\n\n    BenchmarkAlexcesaro-12    \t 5000000\t       333 ns/op\t       0 B/op\t       0 allocs/op\n    BenchmarkGoStatsd-12      \t10000000\t       230 ns/op\t      23 B/op\t       0 allocs/op\n    BenchmarkCactus-12        \t 3000000\t       604 ns/op\t       5 B/op\t       0 allocs/op\n    BenchmarkG2s-12           \t  200000\t      7499 ns/op\t     576 B/op\t      21 allocs/op\n    BenchmarkQuipo-12         \t 1000000\t      1048 ns/op\t     384 B/op\t       7 allocs/op\n    BenchmarkUnix4ever-12        1000000\t      1695 ns/op\t     408 B/op\t      18 allocs/op\n\n## Origins\n\nIdeas were borrowed from the following stastd clients:\n\n* https://github.com/quipo/statsd (MIT License, https://github.com/quipo/statsd/blob/master/LICENSE)\n* https://github.com/Unix4ever/statsd (MIT License, https://github.com/Unix4ever/statsd/blob/master/LICENSE)\n* https://github.com/alexcesaro/statsd/ (MIT License, https://github.com/alexcesaro/statsd/blob/master/LICENSE)\n* https://github.com/armon/go-metrics (MIT License, https://github.com/armon/go-metrics/blob/master/LICENSE)\n\n## Talks\n\nI gave a talk about design and optimizations which went into go-statsd at\n[Gophercon Russia 2018](https://www.gophercon-russia.ru/):\n[slides](https://talks.godoc.org/github.com/smira/gopherconru2018/go-statsd.slide),\n[source](https://github.com/smira/gopherconru2018).\n\n## License\n\nLicense is [MIT License](LICENSE).\n\n\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fsmira%2Fgo-statsd.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fsmira%2Fgo-statsd?ref=badge_large)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmira%2Fgo-statsd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmira%2Fgo-statsd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmira%2Fgo-statsd/lists"}