datadog-go
is a library that provides a DogStatsD client in Golang.
Go 1.7+ is officially supported. Older versions might work but are not tested.
The following documentation is available:
Get the code with:
$ go get github.com/DataDog/datadog-go/statsd
Then create a new DogStatsD client:
package main
import (
"log"
"github.com/DataDog/datadog-go/statsd"
)
func main() {
statsd, err := statsd.New("127.0.0.1:8125")
if err != nil {
log.Fatal(err)
}
}
Find a list of all the available options for your DogStatsD Client in the Datadog-go godoc documentation or in Datadog public DogStatsD documentation.
- If the
addr
parameter is empty, the client uses theDD_AGENT_HOST
and (optionally) theDD_DOGSTATSD_PORT
environment variables to build a target address. - If the
DD_ENTITY_ID
environment variable is found, its value is injected as a globaldd.internal.entity_id
tag. The Datadog Agent uses this tag to insert container tags into the metrics. To avoid overwriting this global tag, onlyappend
to thec.Tags
slice.
To enable origin detection and set the DD_ENTITY_ID
environment variable, add the following lines to your application manifest:
env:
- name: DD_ENTITY_ID
valueFrom:
fieldRef:
fieldPath: metadata.uid
DD_ENV
,DD_SERVICE
, andDD_VERSION
can be used by the statsd client to set{env, service, version}
as global tags for all data emitted.
Agent v6+ accepts packets through a Unix Socket datagram connection. Details about the advantages of using UDS over UDP are available in the DogStatsD Unix Socket documentation. You can use this protocol by giving a unix:///path/to/dsd.socket
address argument to the New
constructor.
In order to use DogStatsD metrics, events, and Service Checks, the Agent must be running and available.
After the client is created, you can start sending custom metrics to Datadog. See the dedicated Metric Submission: DogStatsD documentation to see how to submit all supported metric types to Datadog with working code examples:
- Submit a COUNT metric.
- Submit a GAUGE metric.
- Submit a SET metric
- Submit a HISTOGRAM metric
- Submit a DISTRIBUTION metric
Metric names must only contain ASCII alphanumerics, underscores, and periods. The client will not replace nor check for invalid characters.
Some options are suppported when submitting metrics, like applying a sample rate to your metrics or tagging your metrics with your custom tags. Find all the available functions to report metrics in the Datadog Go client GoDoc documentation.
After the client is created, you can start sending events to your Datadog Event Stream. See the dedicated Event Submission: DogStatsD documentation to see how to submit an event to your Datadog Event Stream.
After the client is created, you can start sending Service Checks to Datadog. See the dedicated Service Check Submission: DogStatsD documentation to see how to submit a Service Check to Datadog.
This client automatically injects telemetry about itself in the DogStatsD stream.
Those metrics will not be counted as custom and will not be billed. This feature can be disabled using the WithoutTelemetry
option.
See Telemetry documentation to learn more about it.
In very high throughput environments it is possible to improve performance by changing the values of some kernel options.
sysctl -w net.unix.max_dgram_qlen=X
- Set datagram queue size to X (default value is usually 10).sysctl -w net.core.wmem_max=X
- Set the max size of the send buffer for all the host sockets.
Run the tests with:
$ go test
datadog-go is released under the MIT license.
Original code by ooyala.