DOCSEARCHbyAlgolia
Submit Docs

datadog-go

repository·master·Indexed 18 days ago

https://github.com/datadog/datadog-go

A Golang implementation of the DogStatsD protocol that allows applications to emit metrics, events, and service checks to a Datadog Agent. It supports metric types including COUNT, GAUGE, SET, HISTOGRAM, and DISTRIBUTION, and provides features such as client-side aggregation, Unix Domain Socket (UDS) support, and configuration via environment variables.

Tokens
1.7K
Snippets
5
Records
11
Agent score
13%

What's inside datadog-go

  2. Submit Metrics, Events, and Service Checks

    master

    Once the client is initialized, you can emit data to the Datadog Agent:

    Metrics

    Supported metric types include:

    • COUNT
    • GAUGE
    • SET
    • HISTOGRAM
    • DISTRIBUTION

    Note: Metric names must only contain ASCII alphanumerics, underscores, and periods. The client does not validate or sanitize characters.

    Events

    Send events to your Datadog Event Stream.

    Service Checks

    Send Service Checks to monitor the health of your services.

  3. Enable Client-Side Aggregation

    master

    Client-side aggregation reduces the number of packets sent to the Agent and minimizes packet drops in high-throughput scenarios by packing multiple values into a single message.

    Basic Aggregation

    Enabled by default. It aggregates gauge, count, and set types.

    • Disable with: WithoutClientSideAggregation()
    • Configure interval with: WithAggregationInterval(duration) (Default is 2s).

    Extended Aggregation

    Disabled by default. It packs multiple values for histogram, distribution, and timing metrics into one message.

    • Compatibility: Requires Agent version >=6.25.0 && <7.0.0 OR Agent version >=7.25.0.
    • Enable with: WithExtendedClientSideAggregation()
    • Benefit: Significantly reduces network usage and packet drops at the cost of slightly higher client CPU/Memory.

    Limiting Samples

    To prevent memory growth during extended aggregation, you can limit the number of samples kept per context.

    • Enable with: WithMaxSamplesPerContext(n int)
    • Default: 0 (no limit).

  4. Use Unix Domain Sockets (UDS) for DogStatsD

    master

    For Agent v6+, you can use Unix Domain Sockets instead of UDP to improve performance. To use UDS, provide a unix:///path/to/dsd.socket address to the statsd.New constructor.

    // Example UDS initialization
statsd, err := statsd.New("unix:///var/run/datadog/dsd.socket")

  5. Install the Datadog Go v5 client

    master

    To use the DogStatsD client in your Go project, install the v5 package using go get. Note that v5 is the current default major version and uses a different import path than v4.

    Import Path for v5: github.com/DataDog/datadog-go/v5/statsd
    Import Path for v4: github.com/DataDog/datadog-go/statsd

    $ go get github.com/DataDog/datadog-go/v5/statsd

  6. Initialize a new DogStatsD client

    master

    Create a new client using statsd.New(addr). If the addr parameter is empty, the client will automatically resolve the address using supported environment variables (see Supported environment variables).

    package main

import (
    "log"
    "github.com/DataDog/datadog-go/v5/statsd"
)

func main() {
    statsd, err := statsd.New("127.0.0.1:8125")
    if err != nil {
        log.Fatal(err)
    }
}

  7. Configure the client via environment variables

    master

    The client supports several environment variables for automatic configuration when no address is provided to statsd.New():

    Connection Settings

    • DD_DOGSTATSD_URL: A URL used to build the target address. Must start with udp:// or unix://.
      • Example UDP: DD_DOGSTATSD_URL=udp://localhost:8125
      • Example UDS: DD_DOGSTATSD_URL=unix:///var/run/datadog/dsd.socket
      • Example Windows Named Pipe: DD_DOGSTATSD_URL=\\.\\pipe\\my_windows_pipe
    • DD_AGENT_HOST: Fallback variable to build the target address.
      • If no port is provided, it defaults to 8125.
      • Supports UDP, UDS, and Windows named pipes.
    • DD_AGENT_PORT: Used to set the port if DD_AGENT_HOST does not contain one (for UDP).

    Global Tagging

    • DD_ENTITY_ID: Injected as a global dd.internal.entity_id tag. Used by the Datadog Agent to associate metrics with containers.
    • DD_ENV, DD_SERVICE, and DD_VERSION: Used to set {env, service, version} as global tags for all emitted data.

  8. Disable client telemetry

    master
    The client automatically injects telemetry about its own performance into the DogStatsD stream. These metrics are not counted as custom metrics and are not billed. If you wish to disable this behavior, use the WithoutTelemetry option.

  9. Optimize Unix Domain Sockets for high throughput

    master

    In high-throughput environments using Unix Domain Sockets, you can improve performance by adjusting kernel options via sysctl:

    • Set datagram queue size: sysctl -w net.unix.max_dgram_qlen=X (default is usually 10).
    • Set max send buffer size: sysctl -w net.core.wmem_max=X.

  10. Set maximum packet size with WithMaxBytesPerPayload

    master

    To optimize network usage in high-throughput scenarios, you can manually set the maximum packet size using the WithMaxBytesPerPayload option.

    package main

import (
    "log"
    "github.com/DataDog/datadog-go/v5/statsd"
)

func main() {
    statsd, err := statsd.New("127.0.0.1:8125", WithMaxBytesPerPayload(4096))
    if err != nil {
        log.Fatal(err)
    }
}

  11. Use ClientInterfaceEx for Cardinality overrides

    master

    The standard ClientInterface has been updated with a new variadic parameter for metric functions. To support existing code or to specifically use the new functionality (like specifying a Cardinality override when creating a metric), use the ClientInterfaceEx interface.

    Access this interface by calling statsd.NewEx(...). Note that ClientInterfaceEx is a temporary measure and will be merged into the main ClientInterface in the next major release.

    package main

import (
    "log"
    "github.com/DataDog/datadog-go/v5/statsd"
)

func main() {
    // Use NewEx to get the ClientInterfaceEx which supports the extra parameter
    statsd, err := statsd.NewEx("127.0.0.1:8125", WithCardinality(CardinalityHigh))
    if err != nil {
        log.Fatal(err)
    }

    // The metric functions now accept an additional Cardinality parameter
    statsd.Gauge("gauge", 32, []string{"environment:dev"}, CardinalityLow)
}