java-dogstatsd-client

by DataDog

a java statsd client library

133 Stars 75 Forks Last release: 4 months ago (v2.10.3) MIT License 319 Commits 41 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

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.

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.

Installation

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

    com.datadoghq
    java-dogstatsd-client
    2.10.3

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

0
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

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 available
    or a
    java.io.IOException: Resource temporarily unavailable
    .

Configuration

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...
}

}

or

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.

Origin detection over UDP and UDS

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

yaml
env:
  - name: DD_ENTITY_ID
    valueFrom:
      fieldRef:
        fieldPath: metadata.uid

Aggregation

As of version 2.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 optional.

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 configured on the client side is smaller than said flush interval on the server side there should no loss in resolution.

Usage

In order to use DogStatsD metrics, events, and Service Checks the Agent must be running and available.

Metrics

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.

Events

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.