orrc / java-dogstatsd-client

a java statsd client library

Java DogStatsD Client

A statsd client library implemented in Java. Allows for Java applications to easily communicate with statsd.

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.

Downloads

The client jar is distributed via maven central, and can be downloaded here.

<dependency>
    <groupId>com.datadoghq</groupId>
    <artifactId>java-dogstatsd-client</artifactId>
    <version>2.6.1</version>
</dependency>

Usage

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

public class Foo {

  private static final StatsDClient statsd = new NonBlockingStatsDClient(
    "my.prefix",                          /* prefix to any stats; may be null or empty string */
    "statsd-host",                        /* common case: localhost */
    8125,                                 /* port */
    new String[] {"tag:value"}            /* Datadog extension: Constant tags, always applied */
  );

  public static final void main(String[] args) {
    statsd.incrementCounter("foo");
    statsd.recordGaugeValue("bar", 100);
    statsd.recordGaugeValue("baz", 0.01); /* DataDog extension: support for floating-point gauges */
    statsd.recordHistogramValue("qux", 15);     /* DataDog extension: histograms */
    statsd.recordHistogramValue("qux", 15.5);   /* ...also floating-point */
    statsd.recordDistributionValue("qux", 15);     /* DataDog extension: global distributions */
    statsd.recordDistributionValue("qux", 15.5);   /* ...also floating-point */

    ServiceCheck sc = ServiceCheck
          .builder()
          .withName("my.check.name")
          .withStatus(ServiceCheck.Status.OK)
          .build();
    statsd.serviceCheck(sc); /* Datadog extension: send service check status */

    /* Compatibility note: Unlike upstream statsd, DataDog expects execution times to be a
     * floating-point value in seconds, not a millisecond value. This library
     * does the conversion from ms to fractional seconds.
     */
    statsd.recordExecutionTime("bag", 25, "cluster:foo"); /* DataDog extension: cluster tag */
  }
}

Unix Domain Socket support

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

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

• Connection error because of an invalid/missing socket will trigger a java.io.IOException: No such file or directory
• If dogstatsd's reception buffer were to fill up, the send will timeout after 100ms and throw either a java.io.IOException: No buffer space available or a java.io.IOException: Resource temporarily unavailable