A DogStatsD client library implemented in Java. Allows for Java applications to easily communicate with the DataDog Agent. 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 java-dogstatsd-client. Collaborating with the former upstream projects we have now combined efforts to provide a single release.
See CHANGELOG.md for changes.
The client jar is distributed via Maven central, and can be downloaded from Maven.
<dependency>
<groupId>com.datadoghq</groupId>
<artifactId>java-dogstatsd-client</artifactId>
<version>4.4.3</version>
</dependency>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
use the address() method of the builder and pass the path to the socket with the unix:// prefix:
StatsDClient client = new NonBlockingStatsDClientBuilder()
.address("unix:///var/run/datadog/dsd.socket")
.build();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 StatsDClientErrorHandler:
- Connection error because of an invalid/missing socket triggers a
java.io.IOException: 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
java.io.IOException: No buffer space availableor ajava.io.IOException: Resource temporarily unavailable.
The default UDS transport is using SOCK_DATAGRAM sockets. We also have experimental support for SOCK_STREAM sockets which can
be enabled by using the unixstream:// instead of unix://. This is not recommended for production use at this time.
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()
.prefix("statsd")
.hostname("localhost")
.port(8125)
.build();
// use your client...
}
}Client version v3.x is now preferred over the older client v2.x release line. We do suggest you upgrade to the newer v3.x at
your earliest convenience.
The builder pattern described above was introduced with v2.10.0 in the v2.x series. Earlier releases require you use the
deprecated overloaded constructors.
DEPRECATED
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.
Though there are very few breaking changes in 3.x, some code changes might be required for some user to migrate to the latest version. If you are migrating from the v2.x series to v3.x 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 constantTags(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) |
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()
.hostname("/var/run/datadog/dsd.socket")
.port(0) // Necessary for unix socket
.maxPacketSizeBytes(16384) // 16kB maximum custom value
.build();Origin detection is a method to detect which pod DogStatsD packets are coming from in order to add the pod's tags to the tag list.
The DogStatsD client attaches an internal tag, entity_id. The value of this tag is the content of the DD_ENTITY_ID 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 append to the constant_tags list.
To enable origin detection over UDP, add the following lines to your application manifest
env:
- name: DD_ENTITY_ID
valueFrom:
fieldRef:
fieldPath: metadata.uidAs of version v2.11.0, 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 v3.0.0, 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 enableAggregation(bool) method on the builder.
There are two clent-side aggregation knobs available:
aggregationShards(int): 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.aggregationFlushInterval(int): 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()
.hostname("localhost")
.port(8125)
.enableAggregation(true)
.aggregationFlushInterval(3000) // optional: in milliseconds
.aggregationShards(8) // optional: defaults to 4
.build();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 HISTOGRAM metric
- Submit a DISTRIBUTION metric
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.
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.
