README.md
1[](https://travis-ci.com/DataDog/datadog-go)
2# Datadog Go
3
4[](https://godoc.org/github.com/DataDog/datadog-go/statsd)
5[](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
){kind=link}
){kind=link}
){kind=link}