1[![Build Status](https://travis-ci.com/DataDog/datadog-go.svg?branch=master)](https://travis-ci.com/DataDog/datadog-go) 2# Datadog Go 3 4[![Godoc](http://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://godoc.org/github.com/DataDog/datadog-go/statsd) 5[![license](http://img.shields.io/badge/license-MIT-red.svg?style=flat)](http://opensource.org/licenses/MIT) 6 7datadog-go is a library that provides a [dogstatsd](http://docs.datadoghq.com/guides/dogstatsd/) client in Golang. 8 9Go 1.7+ is officially supported. Older versions might work but are not tested. 10 11## Get the code 12 13 $ go get github.com/DataDog/datadog-go/statsd 14 15## Usage 16 17Start by creating a new client: 18 19```go 20client, err := statsd.New("127.0.0.1:8125", 21 statsd.WithNamespace("flubber."), // prefix every metric with the app name 22 statsd.WithTags([]string{"region:us-east-1a"}), // send the EC2 availability zone as a tag with every metric 23 // add more options here... 24) 25if err != nil { 26 log.Fatal(err) 27} 28``` 29 30You can find a list of all the available options [here](https://godoc.org/github.com/DataDog/datadog-go/statsd#Option). 31 32After the client is created, you can start sending metrics: 33 34```go 35client.Gauge("kafka.health", 1, []string{"env:production", "partition:1", "partition:2"}, 1) 36``` 37 38Each metric call requires the same parameters: 39 40- `name (string)`: The metric name that will show up in Datadog 41- `value`: The value of the metric. Type depends on the metric type 42- `tags ([]string)`: The list of tags to apply to the metric. Multiple tags can have the same key 43- `rate (float)`: The sampling rate in `[0,1]`. For example `0.5` means that half the calls will result in a metric being sent to Datadog. Set to `1` to disable sampling 44 45You can find all the available functions to report metrics [here](https://godoc.org/github.com/DataDog/datadog-go/statsd#Client). 46 47## Supported environment variables 48 49- The client can use the `DD_AGENT_HOST` and (optionally) the `DD_DOGSTATSD_PORT` environment variables to build the target address if the `addr` parameter is empty. 50- If the `DD_ENTITY_ID` environment variable is found, its value will be injected as a global `dd.internal.entity_id` tag. This tag will be used by the Datadog Agent to insert container tags to the metrics. You should only `append` to the `c.Tags` slice to avoid overwriting this global tag. 51 52To enable origin detection and set the `DD_ENTITY_ID` environment variable, add the following lines to your application manifest 53```yaml 54env: 55 - name: DD_ENTITY_ID 56 valueFrom: 57 fieldRef: 58 fieldPath: metadata.uid 59``` 60 61## Unix Domain Sockets Client 62 63The version 6 (and above) of the Agent accepts packets through a Unix Socket datagram connection. 64Details about the advantages of using UDS over UDP are available in our [docs](https://docs.datadoghq.com/developers/dogstatsd/unix_socket/). 65 66You can use this protocol by giving a `unix:///path/to/dsd.socket` address argument to the `New` constructor. 67 68## Performance / Metric drops 69 70### Tweaking kernel options 71 72In very high throughput environments it is possible to improve performance by changing the values of some kernel options. 73 74#### Unix Domain Sockets 75 76- `sysctl -w net.unix.max_dgram_qlen=X` - Set datagram queue size to X (default value is usually 10). 77- `sysctl -w net.core.wmem_max=X` - Set the max size of the send buffer for all the host sockets. 78 79## Development 80 81Run the tests with: 82 83 $ go test 84 85## Documentation 86 87Please see: http://godoc.org/github.com/DataDog/datadog-go/statsd 88 89## License 90 91datadog-go is released under the [MIT license](http://www.opensource.org/licenses/mit-license.php). 92 93## Credits 94 95Original code by [ooyala](https://github.com/ooyala/go-dogstatsd). 96