com.github.arnabk.statsd

Class BlockingStatsDClient

java.lang.Object

com.github.arnabk.statsd.BlockingStatsDClient

All Implemented Interfaces:

StatsDClient

public class BlockingStatsDClient
extends Object
implements StatsDClient

A simple StatsD client implementation facilitating metrics recording.

Upon instantiation, this client will establish a socket connection to a StatsD instance running on the specified host and port. Metrics are then sent over this connection as they are received by the client.

Three key methods are provided for the submission of data-points for the application under scrutiny:

• incrementCounter(java.lang.String, java.lang.String...) - adds one to the value of the specified named counter
• recordGaugeValue(java.lang.String, double, java.lang.String...) - records the latest fixed value for the specified named gauge
• recordExecutionTime(java.lang.String, long, java.lang.String...) - records an execution time in milliseconds for the specified named operation
• recordHistogramValue(java.lang.String, double, java.lang.String...) - records a value, to be tracked with average, maximum, and percentiles

As part of a clean system shutdown, the stop() method should be invoked on any StatsD clients.

This class is a blocking implementation. It is preferable to use with already existing threading systems or logging systems like slf4j(log4j implementation)

Author:

Arnab

Field Summary

Fields

Modifier and Type	Field and Description
protected DatagramSocket	clientSocket
protected String[]	constantTags
protected StatsDClientErrorHandler	handler
protected static StatsDClientErrorHandler	NO_OP_HANDLER
protected static ThreadLocal<NumberFormat>	NUMBER_FORMATTERS Because NumberFormat is not thread-safe we cannot share instances across threads.
protected String	prefix

Constructor Summary

Constructors

Constructor and Description
BlockingStatsDClient(String prefix, String hostname, int port) Create a new StatsD client communicating with a StatsD instance on the specified host and port.
BlockingStatsDClient(String prefix, String hostname, int port, String[] constantTags) Create a new StatsD client communicating with a StatsD instance on the specified host and port.
BlockingStatsDClient(String prefix, String hostname, int port, String[] constantTags, StatsDClientErrorHandler errorHandler) Create a new StatsD client communicating with a StatsD instance on the specified host and port.

Method Summary

Methods

Modifier and Type	Method and Description
void	count(String aspect, long delta, String... tags) Adjusts the specified counter by a given delta.
void	decrement(String aspect, String... tags) Convenience method equivalent to decrementCounter(String, String[]).
void	decrementCounter(String aspect, String... tags) Decrements the specified counter by one.
void	gauge(String aspect, double value, String... tags) Convenience method equivalent to recordGaugeValue(String, double, String[]).
void	gauge(String aspect, long value, String... tags) Convenience method equivalent to #recordGaugeValue(String, int, String[]).
void	histogram(String aspect, double value, String... tags) Convenience method equivalent to recordHistogramValue(String, double, String[]).
void	histogram(String aspect, long value, String... tags) Convenience method equivalent to #recordHistogramValue(String, int, String[]).
void	increment(String aspect, String... tags) Convenience method equivalent to incrementCounter(String, String[]).
void	incrementCounter(String aspect, String... tags) Increments the specified counter by one.
void	recordExecutionTime(String aspect, long timeInMs, String... tags) Records an execution time in milliseconds for the specified named operation.
void	recordGaugeValue(String aspect, double value, String... tags) Records the latest fixed value for the specified named gauge.
void	recordGaugeValue(String aspect, long value, String... tags) Records the latest fixed value for the specified named gauge.
void	recordHistogramValue(String aspect, double value, String... tags) Records a value for the specified named histogram.
void	recordHistogramValue(String aspect, long value, String... tags) Records a value for the specified named histogram.
void	stop() Cleanly shut down this StatsD client.
void	time(String aspect, long value, String... tags) Convenience method equivalent to recordExecutionTime(String, long, String[]).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_OP_HANDLER

protected static final StatsDClientErrorHandler NO_OP_HANDLER

NUMBER_FORMATTERS

protected static final ThreadLocal<NumberFormat> NUMBER_FORMATTERS

Because NumberFormat is not thread-safe we cannot share instances across threads. Use a ThreadLocal to create one pre thread as this seems to offer a significant performance improvement over creating one per-thread: http://stackoverflow.com/a/1285297/2648 https://github.com/indeedeng/java-dogstatsd-client/issues/4

prefix

protected final String prefix

clientSocket

protected final DatagramSocket clientSocket

handler

protected final StatsDClientErrorHandler handler

constantTags

protected final String[] constantTags

Constructor Detail

BlockingStatsDClient

public BlockingStatsDClient(String prefix,
                    String hostname,
                    int port)
                     throws StatsDClientException

Create a new StatsD client communicating with a StatsD instance on the specified host and port. All messages send via this client will have their keys prefixed with the specified string. The new client will attempt to open a connection to the StatsD server immediately upon instantiation, and may throw an exception if that a connection cannot be established. Once a client has been instantiated in this way, all exceptions thrown during subsequent usage are consumed, guaranteeing that failures in metrics will not affect normal code execution.

Parameters:

prefix - the prefix to apply to keys sent via this client

hostname - the host name of the targeted StatsD server

port - the port of the targeted StatsD server

Throws:

StatsDClientException - if the client could not be started

BlockingStatsDClient

public BlockingStatsDClient(String prefix,
                    String hostname,
                    int port,
                    String[] constantTags)
                     throws StatsDClientException

Create a new StatsD client communicating with a StatsD instance on the specified host and port. All messages send via this client will have their keys prefixed with the specified string. The new client will attempt to open a connection to the StatsD server immediately upon instantiation, and may throw an exception if that a connection cannot be established. Once a client has been instantiated in this way, all exceptions thrown during subsequent usage are consumed, guaranteeing that failures in metrics will not affect normal code execution.

Parameters:

prefix - the prefix to apply to keys sent via this client

hostname - the host name of the targeted StatsD server

port - the port of the targeted StatsD server

constantTags - tags to be added to all content sent

Throws:

StatsDClientException - if the client could not be started

BlockingStatsDClient

public BlockingStatsDClient(String prefix,
                    String hostname,
                    int port,
                    String[] constantTags,
                    StatsDClientErrorHandler errorHandler)
                     throws StatsDClientException

Create a new StatsD client communicating with a StatsD instance on the specified host and port. All messages send via this client will have their keys prefixed with the specified string. The new client will attempt to open a connection to the StatsD server immediately upon instantiation, and may throw an exception if that a connection cannot be established. Once a client has been instantiated in this way, all exceptions thrown during subsequent usage are passed to the specified handler and then consumed, guaranteeing that failures in metrics will not affect normal code execution.

Parameters:

prefix - the prefix to apply to keys sent via this client

hostname - the host name of the targeted StatsD server

port - the port of the targeted StatsD server

constantTags - tags to be added to all content sent

errorHandler - handler to use when an exception occurs during usage

Throws:

StatsDClientException - if the client could not be started

Method Detail

stop

public void stop()

Cleanly shut down this StatsD client. This method may throw an exception if the socket cannot be closed.

Specified by:

stop in interface StatsDClient

count

public void count(String aspect,
         long delta,
         String... tags)

Adjusts the specified counter by a given delta.

Specified by:

count in interface StatsDClient

Parameters:

aspect - the name of the counter to adjust

delta - the amount to adjust the counter by

tags - array of tags to be added to the data

incrementCounter

public void incrementCounter(String aspect,
                    String... tags)

Increments the specified counter by one.

Specified by:

incrementCounter in interface StatsDClient

Parameters:

aspect - the name of the counter to increment

tags - array of tags to be added to the data

increment

public void increment(String aspect,
             String... tags)

Convenience method equivalent to incrementCounter(String, String[]).

Specified by:

increment in interface StatsDClient

decrementCounter

public void decrementCounter(String aspect,
                    String... tags)

Decrements the specified counter by one.

Specified by:

decrementCounter in interface StatsDClient

Parameters:

aspect - the name of the counter to decrement

tags - array of tags to be added to the data

decrement

public void decrement(String aspect,
             String... tags)

Convenience method equivalent to decrementCounter(String, String[]).

Specified by:

decrement in interface StatsDClient

recordGaugeValue

public void recordGaugeValue(String aspect,
                    double value,
                    String... tags)

Records the latest fixed value for the specified named gauge.

Specified by:

recordGaugeValue in interface StatsDClient

Parameters:

aspect - the name of the gauge

value - the new reading of the gauge

tags - array of tags to be added to the data

gauge

public void gauge(String aspect,
         double value,
         String... tags)

Convenience method equivalent to recordGaugeValue(String, double, String[]).

Specified by:

gauge in interface StatsDClient

recordGaugeValue

public void recordGaugeValue(String aspect,
                    long value,
                    String... tags)

Records the latest fixed value for the specified named gauge.

Specified by:

recordGaugeValue in interface StatsDClient

Parameters:

aspect - the name of the gauge

value - the new reading of the gauge

tags - array of tags to be added to the data

gauge

public void gauge(String aspect,
         long value,
         String... tags)

Convenience method equivalent to #recordGaugeValue(String, int, String[]).

Specified by:

gauge in interface StatsDClient

recordExecutionTime

public void recordExecutionTime(String aspect,
                       long timeInMs,
                       String... tags)

Records an execution time in milliseconds for the specified named operation.

Specified by:

recordExecutionTime in interface StatsDClient

Parameters:

aspect - the name of the timed operation

timeInMs - the time in milliseconds

tags - array of tags to be added to the data

time

public void time(String aspect,
        long value,
        String... tags)

Convenience method equivalent to recordExecutionTime(String, long, String[]).

Specified by:

time in interface StatsDClient

recordHistogramValue

public void recordHistogramValue(String aspect,
                        double value,
                        String... tags)

Records a value for the specified named histogram.

Specified by:

recordHistogramValue in interface StatsDClient

Parameters:

aspect - the name of the histogram

value - the value to be incorporated in the histogram

tags - array of tags to be added to the data

histogram

public void histogram(String aspect,
             double value,
             String... tags)

Convenience method equivalent to recordHistogramValue(String, double, String[]).

Specified by:

histogram in interface StatsDClient

recordHistogramValue

public void recordHistogramValue(String aspect,
                        long value,
                        String... tags)

Records a value for the specified named histogram.

Specified by:

recordHistogramValue in interface StatsDClient

Parameters:

aspect - the name of the histogram

value - the value to be incorporated in the histogram

tags - array of tags to be added to the data

histogram

public void histogram(String aspect,
             long value,
             String... tags)

Convenience method equivalent to #recordHistogramValue(String, int, String[]).

Specified by:

histogram in interface StatsDClient