Need help with java-dogstatsd-client?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

150 Stars 88 Forks MIT License 398 Commits 36 Opened issues


Java statsd client library

Services available


Need anything else?

Contributors list

Java DogStatsD Client

CircleCI Build Status Travis Build Status

A StatsD client library implemented in Java. Allows for Java applications to easily communicate with statsd. The library supports Java 1.7+.

This version was originally forked from java-dogstatsd-client and java-statsd-client but it is now the canonical home for the

. Collaborating with the former upstream projects we have now combined efforts to provide a single release.

See for changes.


The client jar is distributed via Maven central, and can be downloaded from Maven.


Unix Domain Socket support

As an alternative to UDP, Agent v6 can receive metrics via a UNIX Socket (on Linux only). This library supports transmission via this protocol. To use it, pass the socket path as a hostname, and

as port.

By default, all exceptions are ignored, mimicking UDP behaviour. When using Unix Sockets, transmission errors trigger exceptions you can choose to handle by passing a

  • Connection error because of an invalid/missing socket triggers a No such file or directory
  • If DogStatsD's reception buffer were to fill up and the non blocking client is used, the send times out after 100ms and throw either a No buffer space available
    or a Resource temporarily unavailable


Once your DogStatsD client is installed, instantiate it in your code:

import com.timgroup.statsd.NonBlockingStatsDClientBuilder;
import com.timgroup.statsd.NonBlockingStatsDClient;
import com.timgroup.statsd.StatsDClient;

public class DogStatsdClient {

public static void main(String[] args) throws Exception {

    StatsDClient client = new NonBlockingStatsDClientBuilder()

    // use your client...



import com.timgroup.statsd.NonBlockingStatsDClientBuilder;
import com.timgroup.statsd.NonBlockingStatsDClient;
import com.timgroup.statsd.StatsDClient;

public class DogStatsdClient {

public static void main(String[] args) throws Exception {

    // resolve() returns a copy of NonBlockingStatsDClient with
    // any implicit elements resolved, and may also be passed to
    // NonBlockingStatsDClient to as a sole constructor argument.

    StatsDClient client = new NonBlockingStatsDClient(
        new NonBlockingStatsDClientBuilder()

    // use your client...



Client version

is now preferred over the older client
release line. We do suggest you upgrade to the newer
at your earliest convenience.

The builder pattern described above was introduced with

in the
series. Earlier releases require you use the deprecated overloaded constructors.

DEPRECATED ```java import com.timgroup.statsd.NonBlockingStatsDClient; import com.timgroup.statsd.StatsDClient;

public class DogStatsdClient {

public static void main(String[] args) throws Exception {

StatsDClient Statsd = new NonBlockingStatsDClient("statsd", "localhost", 8125);


} ```

See the full list of available DogStatsD Client instantiation parameters.

Migrating from 2.x to 3.x

Though there are very few breaking changes in

, some code changes might be required for some user to migrate to the latest version. If you are migrating from the
series to
and were using the deprecated constructors, please use the following table to ease your migration to utilizing the builder pattern.

| v2.x constructor parameter | v2.10.0+ builder method | |----------------------------|-------------------------| | final Callable addressLookup | NonBlockingStatsDClientBuilder addressLookup(Callable val) | | final boolean blocking | NonBlockingStatsDClientBuilder blocking(boolean val) | | final int bufferSize | NonBlockingStatsDClientBuilder socketBufferSize(int val) | | final String... constantTags | NonBlockingStatsDClientBuilder queueSize(String... val) | | final boolean enableTelemetry | NonBlockingStatsDClientBuilder enableTelemetry(boolean val) | | final String entityID | NonBlockingStatsDClientBuilder entityID(String val) | | final StatsDClientErrorHandler errorHandler | NonBlockingStatsDClientBuilder errorHandler(StatsDClientErrorHandler val) | | final String hostname | NonBlockingStatsDClientBuilder hostname(String val) | | final int maxPacketSizeBytes | NonBlockingStatsDClientBuilder maxPacketSizeBytes(String... val) | | final int processorWorkers | NonBlockingStatsDClientBuilder processorWorkers(int val) | | final int poolSize | NonBlockingStatsDClientBuilder bufferPoolSize(int val) | | final int port | NonBlockingStatsDClientBuilder port(int val) | | final String prefix | NonBlockingStatsDClientBuilder prefix(String val) | | final int queueSize | NonBlockingStatsDClientBuilder queueSize(int val) | | final int senderWorkers | NonBlockingStatsDClientBuilder senderWorkers(int val) | | final Callable telemetryAddressLookup | NonBlockingStatsDClientBuilder telemetryAddressLookup(Callable val) | | final int telemetryFlushInterval | NonBlockingStatsDClientBuilder telemetryFlushInterval(int val) | | final int timeout | NonBlockingStatsDClientBuilder timeout(int val) |

Transport and Maximum Packet Size

As mentioned above the client currently supports two forms of transport: UDP and Unix Domain Sockets (UDS).

The preferred setup for local transport is UDS, while remote setups will require the use of UDP. For both setups we have tried to set convenient maximum default packet sizes that should help with performance by packing multiple statsd metrics into each network packet all while playing nicely with the respective environments. For this reason we have set the following defaults for the max packet size: - UDS: 8192 bytes - recommended default. - UDP: 1432 bytes - largest possible size given the Ethernet MTU of 1514 Bytes. This should help avoid UDP fragmentation.

These are both configurable should you have other needs:

StatsDClient client = new NonBlockingStatsDClientBuilder()
    .maxPacketSizeBytes(16384)  // 16kB maximum custom value

Origin detection over UDP and UDS

Origin detection is a method to detect which pod

packets are coming from in order to add the pod's tags to the tag list. The
client attaches an internal tag,
. The value of this tag is the content of the
environment variable if found, which is the pod's UID. The Datadog Agent uses this tag to add container tags to the metrics. To avoid overwriting this global tag, make sure to only
to the

To enable origin detection over UDP, add the following lines to your application manifest

  - name: DD_ENTITY_ID
        fieldPath: metadata.uid


As of version

, client-side aggregation has been introduced in the java client side for basic types (gauges, counts, sets). Aggregation remains unavailable at the time of this writing for histograms, distributions, service checks and events due to message relevance and statistical significance of these types. The feature is enabled by default as of
, and remains available but disabled by default for prior versions.

The goal of this feature is to reduce the number of messages submitted to the Datadog Agent. Minimizing message volume allows us to reduce load on the dogstatsd server side and mitigate packet drops. The feature has been implemented such that impact on CPU and memory should be quite minimal on the client side. Users might be concerned with what could be perceived as a loss of resolution by resorting to aggregation on the client, this should not be the case. It's worth noting the dogstatsd server implemented in the Datadog Agent already aggregates messages over a certain flush period, therefore so long as the flush interval configured on the client side is smaller than said flush interval on the server side there should no loss in resolution.


Enabling aggregation is simple, you just need to set the appropriate options with the client builder.

You can just enable aggregation by calling the

method on the builder.

There are two clent-side aggregation knobs available: -

: determines the number of shards in the aggregator, this feature is aimed at mitigating the effects of map locking in highly concurrent scenarios. Defaults to 4. -
: sets the period of time in milliseconds in which the aggregator will flush its metrics into the sender. Defaults to 3000 milliseconds.
StatsDClient client = new NonBlockingStatsDClientBuilder()
    .aggregationFlushInterval(3000)  // optional: in milliseconds
    .aggregationShards(8)  // optional: defaults to 4


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:

Some options are suppported when submitting metrics, like applying a Sample Rate to your metrics or tagging your metrics with your custom tags.


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.

Service Checks

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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.