com.timgroup.statsd

Class NonBlockingStatsDClient

java.lang.Object

com.timgroup.statsd.NonBlockingStatsDClient

All Implemented Interfaces:

StatsDClient, Closeable, AutoCloseable

public class NonBlockingStatsDClient
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
• recordEvent(com.timgroup.statsd.Event, java.lang.String...) - records an event
• recordSetValue(java.lang.String, java.lang.String, java.lang.String...) - records a value in a set

From the perspective of the application, these methods are non-blocking, with the resulting IO operations being carried out in a separate thread. Furthermore, these methods are guaranteed not to throw an exception which may disrupt application execution.

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

Author:

Tom Denley

Field Summary

Fields

Modifier and Type	Field and Description
static String	DD_AGENT_HOST_ENV_VAR
static String	DD_DOGSTATSD_PORT_ENV_VAR
static String	DD_ENTITY_ID_ENV_VAR

Constructor Summary

Constructors

Constructor and Description
NonBlockingStatsDClient(String prefix) Create a new StatsD client communicating with a StatsD instance.
NonBlockingStatsDClient(String prefix, int queueSize, String[] constantTags, StatsDClientErrorHandler errorHandler, Callable<SocketAddress> addressLookup) Create a new StatsD client communicating with a StatsD instance on the specified host and port.
NonBlockingStatsDClient(String prefix, int queueSize, String[] constantTags, StatsDClientErrorHandler errorHandler, Callable<SocketAddress> addressLookup, int timeout, int bufferSize) Create a new StatsD client communicating with a StatsD instance on the specified host and port.
NonBlockingStatsDClient(String prefix, int queueSize, String[] constantTags, StatsDClientErrorHandler errorHandler, Callable<SocketAddress> addressLookup, int timeout, int bufferSize, int maxPacketSizeBytes) Create a new StatsD client communicating with a StatsD instance on the specified host and port.
NonBlockingStatsDClient(String prefix, int queueSize, String[] constantTags, StatsDClientErrorHandler errorHandler, Callable<SocketAddress> addressLookup, int timeout, int bufferSize, int maxPacketSizeBytes, String entityID) Create a new StatsD client communicating with a StatsD instance on the specified host and port.
NonBlockingStatsDClient(String prefix, String hostname, int port) Create a new StatsD client communicating with a StatsD instance on the specified host and port.
NonBlockingStatsDClient(String prefix, String hostname, int port, int queueSize) Create a new StatsD client communicating with a StatsD instance on the specified host and port.
NonBlockingStatsDClient(String prefix, String hostname, int port, int queueSize, int timeout, int bufferSize, String[] constantTags, StatsDClientErrorHandler errorHandler) Create a new StatsD client communicating with a StatsD instance on the specified host and port.
NonBlockingStatsDClient(String prefix, String hostname, int port, int queueSize, String... constantTags) Create a new StatsD client communicating with a StatsD instance on the specified host and port.
NonBlockingStatsDClient(String prefix, String hostname, int port, int queueSize, String[] constantTags, StatsDClientErrorHandler errorHandler) Create a new StatsD client communicating with a StatsD instance on the specified host and port.
NonBlockingStatsDClient(String prefix, String hostname, int port, int queueSize, String[] constantTags, StatsDClientErrorHandler errorHandler, int maxPacketSizeBytes) Create a new StatsD client communicating with a StatsD instance on the specified host and port.
NonBlockingStatsDClient(String prefix, String hostname, int port, int queueSize, String[] constantTags, StatsDClientErrorHandler errorHandler, String entityID) Create a new StatsD client communicating with a StatsD instance on the specified host and port.
NonBlockingStatsDClient(String prefix, String hostname, int port, String... constantTags) Create a new StatsD client communicating with a StatsD instance on the specified host and port.
NonBlockingStatsDClient(String prefix, String hostname, int port, String[] constantTags, int maxPacketSizeBytes) Create a new StatsD client communicating with a StatsD instance on the specified host and port.
NonBlockingStatsDClient(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

Modifier and Type	Method and Description
void	close()
void	count(String aspect, double delta, double sampleRate, String... tags) Adjusts the specified counter by a given delta.
void	count(String aspect, double delta, String... tags) Adjusts the specified counter by a given delta.
void	count(String aspect, long delta, double sampleRate, String... tags) Adjusts the specified counter by a given delta.
void	count(String aspect, long delta, String... tags) Adjusts the specified counter by a given delta.
protected StatsDSender	createSender(Callable<SocketAddress> addressLookup, int queueSize, StatsDClientErrorHandler handler, DatagramChannel clientChannel, int maxPacketSizeBytes)
void	decrement(String aspect, double sampleRate, String... tags) Convenience method equivalent to StatsDClient.decrementCounter(String, double, String[]).
void	decrement(String aspect, String... tags) Convenience method equivalent to decrementCounter(String, String[]).
void	decrementCounter(String aspect, double sampleRate, String... tags) Decrements the specified counter by one.
void	decrementCounter(String aspect, String... tags) Decrements the specified counter by one.
void	distribution(String aspect, double value, double sampleRate, String... tags) Convenience method equivalent to StatsDClient.recordDistributionValue(String, double, double, String[]).
void	distribution(String aspect, double value, String... tags) Convenience method equivalent to recordDistributionValue(String, double, String[]).
void	distribution(String aspect, long value, double sampleRate, String... tags) Convenience method equivalent to StatsDClient.recordDistributionValue(String, long, double, String[]).
void	distribution(String aspect, long value, String... tags) Convenience method equivalent to recordDistributionValue(String, long, String[]).
void	gauge(String aspect, double value, double sampleRate, String... tags) Convenience method equivalent to StatsDClient.recordGaugeValue(String, double, double, String[]).
void	gauge(String aspect, double value, String... tags) Convenience method equivalent to recordGaugeValue(String, double, String[]).
void	gauge(String aspect, long value, double sampleRate, String... tags) Convenience method equivalent to StatsDClient.recordGaugeValue(String, long, double, String[]).
void	gauge(String aspect, long value, String... tags) Convenience method equivalent to recordGaugeValue(String, long, String[]).
void	histogram(String aspect, double value, double sampleRate, String... tags) Convenience method equivalent to StatsDClient.recordHistogramValue(String, double, double, String[]).
void	histogram(String aspect, double value, String... tags) Convenience method equivalent to recordHistogramValue(String, double, String[]).
void	histogram(String aspect, long value, double sampleRate, String... tags) Convenience method equivalent to StatsDClient.recordHistogramValue(String, long, double, String[]).
void	histogram(String aspect, long value, String... tags) Convenience method equivalent to recordHistogramValue(String, long, String[]).
void	increment(String aspect, double sampleRate, String... tags) Convenience method equivalent to StatsDClient.incrementCounter(String, double, String[]).
void	increment(String aspect, String... tags) Convenience method equivalent to incrementCounter(String, String[]).
void	incrementCounter(String aspect, double sampleRate, String... tags) Increments the specified counter by one.
void	incrementCounter(String aspect, String... tags) Increments the specified counter by one.
void	recordDistributionValue(String aspect, double value, double sampleRate, String... tags) Records a value for the specified named distribution.
void	recordDistributionValue(String aspect, double value, String... tags) Records a value for the specified named distribution.
void	recordDistributionValue(String aspect, long value, double sampleRate, String... tags) Records a value for the specified named distribution.
void	recordDistributionValue(String aspect, long value, String... tags) Records a value for the specified named distribution.
void	recordEvent(Event event, String... tags) Records an event
void	recordExecutionTime(String aspect, long timeInMs, double sampleRate, String... tags) Records an execution time in milliseconds for the specified named operation.
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, double sampleRate, String... tags) Records the latest fixed value for the specified named gauge.
void	recordGaugeValue(String aspect, double value, String... tags) Records the latest fixed value for the specified named gauge.
void	recordGaugeValue(String aspect, long value, double sampleRate, 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, double sampleRate, String... tags) Records a value for the specified named histogram.
void	recordHistogramValue(String aspect, double value, String... tags) Records a value for the specified named histogram.
void	recordHistogramValue(String aspect, long value, double sampleRate, 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	recordServiceCheckRun(ServiceCheck sc) Records a run status for the specified named service check.
void	recordSetValue(String aspect, String value, String... tags) Records a value for the specified set.
void	serviceCheck(ServiceCheck sc) Convenience method equivalent to recordServiceCheckRun(ServiceCheck sc).
static Callable<SocketAddress>	staticAddressResolution(String hostname, int port) Lookup the address for the given host name and cache the result.
void	stop() Cleanly shut down this StatsD client.
void	time(String aspect, long value, double sampleRate, String... tags) Convenience method equivalent to StatsDClient.recordExecutionTime(String, long, double, String[]).
void	time(String aspect, long value, String... tags) Convenience method equivalent to recordExecutionTime(String, long, String[]).
static Callable<SocketAddress>	volatileAddressResolution(String hostname, int port) Create dynamic lookup for the given host name and port.

Methods inherited from class java.lang.Object

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

Field Detail

DD_ENTITY_ID_ENV_VAR

public static final String DD_ENTITY_ID_ENV_VAR

See Also:

Constant Field Values

DD_DOGSTATSD_PORT_ENV_VAR

public static final String DD_DOGSTATSD_PORT_ENV_VAR

See Also:

Constant Field Values

DD_AGENT_HOST_ENV_VAR

public static final String DD_AGENT_HOST_ENV_VAR

See Also:

Constant Field Values

Constructor Detail

NonBlockingStatsDClient

public NonBlockingStatsDClient(String prefix)
                        throws StatsDClientException

Create a new StatsD client communicating with a StatsD instance. It uses Environment variables ("DD_AGENT_HOST" and "DD_DOGSTATSD_PORT") in order to configure the communication with a StatsD instance. 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

Throws:

StatsDClientException - if the client could not be started

NonBlockingStatsDClient

public NonBlockingStatsDClient(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. If 'null' the environment variable "DD_AGENT_HOST" is used to get the host name.

port - the port of the targeted StatsD server. If the parameter 'hostname' is 'null' and this parameter is equal to '0', the environment variable "DD_DOGSTATSD_PORT" is used to get the port, else the default value '8125' is used.

Throws:

StatsDClientException - if the client could not be started

NonBlockingStatsDClient

public NonBlockingStatsDClient(String prefix,
                               String hostname,
                               int port,
                               int queueSize)
                        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. If 'null' the environment variable "DD_AGENT_HOST" is used to get the host name.

port - the port of the targeted StatsD server. If the parameter 'hostname' is 'null' and this parameter is equal to '0', the environment variable "DD_DOGSTATSD_PORT" is used to get the port, else the default value '8125' is used.

queueSize - the maximum amount of unprocessed messages in the BlockingQueue.

Throws:

StatsDClientException - if the client could not be started

NonBlockingStatsDClient

public NonBlockingStatsDClient(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. If 'null' the environment variable "DD_AGENT_HOST" is used to get the host name.

port - the port of the targeted StatsD server. If the parameter 'hostname' is 'null' and this parameter is equal to '0', the environment variable "DD_DOGSTATSD_PORT" is used to get the port, else the default value '8125' is used.

constantTags - tags to be added to all content sent

Throws:

StatsDClientException - if the client could not be started

NonBlockingStatsDClient

public NonBlockingStatsDClient(String prefix,
                               String hostname,
                               int port,
                               String[] constantTags,
                               int maxPacketSizeBytes)
                        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. If 'null' the environment variable "DD_AGENT_HOST" is used to get the host name.

port - the port of the targeted StatsD server. If the parameter 'hostname' is 'null' and this parameter is equal to '0', the environment variable "DD_DOGSTATSD_PORT" is used to get the port, else the default value '8125' is used.

constantTags - tags to be added to all content sent

maxPacketSizeBytes - the maximum number of bytes for a message that can be sent

Throws:

StatsDClientException - if the client could not be started

NonBlockingStatsDClient

public NonBlockingStatsDClient(String prefix,
                               String hostname,
                               int port,
                               int queueSize,
                               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. If 'null' the environment variable "DD_AGENT_HOST" is used to get the host name.

port - the port of the targeted StatsD server. If the parameter 'hostname' is 'null' and this parameter is equal to '0', the environment variable "DD_DOGSTATSD_PORT" is used to get the port, else the default value '8125' is used.

constantTags - tags to be added to all content sent

queueSize - the maximum amount of unprocessed messages in the BlockingQueue.

Throws:

StatsDClientException - if the client could not be started

NonBlockingStatsDClient

public NonBlockingStatsDClient(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. If 'null' the environment variable "DD_AGENT_HOST" is used to get the host name.

port - the port of the targeted StatsD server. If the parameter 'hostname' is 'null' and this parameter is equal to '0', the environment variable "DD_DOGSTATSD_PORT" is used to get the port, else the default value '8125' is used.

constantTags - tags to be added to all content sent

errorHandler - handler to use when an exception occurs during usage, may be null to indicate noop

Throws:

StatsDClientException - if the client could not be started

NonBlockingStatsDClient

public NonBlockingStatsDClient(String prefix,
                               String hostname,
                               int port,
                               int queueSize,
                               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. If 'null' the environment variable "DD_AGENT_HOST" is used to get the host name.

port - the port of the targeted StatsD server. If the parameter 'hostname' is 'null' and this parameter is equal to '0', the environment variable "DD_DOGSTATSD_PORT" is used to get the port, else the default value '8125' is used.

constantTags - tags to be added to all content sent

errorHandler - handler to use when an exception occurs during usage, may be null to indicate noop

queueSize - the maximum amount of unprocessed messages in the BlockingQueue.

Throws:

StatsDClientException - if the client could not be started

NonBlockingStatsDClient

public NonBlockingStatsDClient(String prefix,
                               String hostname,
                               int port,
                               int queueSize,
                               String[] constantTags,
                               StatsDClientErrorHandler errorHandler,
                               String entityID)
                        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. If 'null' the environment variable "DD_AGENT_HOST" is used to get the host name.

port - the port of the targeted StatsD server. If the parameter 'hostname' is 'null' and this parameter is equal to '0', the environment variable "DD_DOGSTATSD_PORT" is used to get the port, else the default value '8125' is used.

constantTags - tags to be added to all content sent

errorHandler - handler to use when an exception occurs during usage, may be null to indicate noop

queueSize - the maximum amount of unprocessed messages in the BlockingQueue.

entityID - the entity id value used with an internal tag for tracking client entity. If "entityID=null" the client default the value with the environment variable "DD_ENTITY_ID". If the environment variable is not defined, the internal tag is not added.

Throws:

StatsDClientException - if the client could not be started

NonBlockingStatsDClient

public NonBlockingStatsDClient(String prefix,
                               String hostname,
                               int port,
                               int queueSize,
                               String[] constantTags,
                               StatsDClientErrorHandler errorHandler,
                               int maxPacketSizeBytes)
                        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. If 'null' the environment variable "DD_AGENT_HOST" is used to get the host name.

port - the port of the targeted StatsD server. If the parameter 'hostname' is 'null' and this parameter is equal to '0', the environment variable "DD_DOGSTATSD_PORT" is used to get the port, else the default value '8125' is used.

constantTags - tags to be added to all content sent

errorHandler - handler to use when an exception occurs during usage, may be null to indicate noop

queueSize - the maximum amount of unprocessed messages in the BlockingQueue.

maxPacketSizeBytes - the maximum number of bytes for a message that can be sent

Throws:

StatsDClientException - if the client could not be started

NonBlockingStatsDClient

public NonBlockingStatsDClient(String prefix,
                               String hostname,
                               int port,
                               int queueSize,
                               int timeout,
                               int bufferSize,
                               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. If 'null' the environment variable "DD_AGENT_HOST" is used to get the host name.

port - the port of the targeted StatsD server. If the parameter 'hostname' is 'null' and this parameter is equal to '0', the environment variable "DD_DOGSTATSD_PORT" is used to get the port, else the default value '8125' is used.

constantTags - tags to be added to all content sent

errorHandler - handler to use when an exception occurs during usage, may be null to indicate noop

queueSize - the maximum amount of unprocessed messages in the BlockingQueue.

timeout - the timeout in milliseconds for blocking operations. Applies to unix sockets only.

bufferSize - the socket buffer size in bytes. Applies to unix sockets only.

Throws:

StatsDClientException - if the client could not be started

NonBlockingStatsDClient

public NonBlockingStatsDClient(String prefix,
                               int queueSize,
                               String[] constantTags,
                               StatsDClientErrorHandler errorHandler,
                               Callable<SocketAddress> addressLookup)
                        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

constantTags - tags to be added to all content sent

errorHandler - handler to use when an exception occurs during usage, may be null to indicate noop

addressLookup - yields the IP address and socket of the StatsD server

queueSize - the maximum amount of unprocessed messages in the BlockingQueue.

Throws:

StatsDClientException - if the client could not be started

NonBlockingStatsDClient

public NonBlockingStatsDClient(String prefix,
                               int queueSize,
                               String[] constantTags,
                               StatsDClientErrorHandler errorHandler,
                               Callable<SocketAddress> addressLookup,
                               int timeout,
                               int bufferSize)
                        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

constantTags - tags to be added to all content sent

errorHandler - handler to use when an exception occurs during usage, may be null to indicate noop

addressLookup - yields the IP address and socket of the StatsD server

queueSize - the maximum amount of unprocessed messages in the BlockingQueue.

timeout - the timeout in milliseconds for blocking operations. Applies to unix sockets only.

bufferSize - the socket buffer size in bytes. Applies to unix sockets only.

Throws:

StatsDClientException - if the client could not be started

NonBlockingStatsDClient

public NonBlockingStatsDClient(String prefix,
                               int queueSize,
                               String[] constantTags,
                               StatsDClientErrorHandler errorHandler,
                               Callable<SocketAddress> addressLookup,
                               int timeout,
                               int bufferSize,
                               int maxPacketSizeBytes)
                        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

constantTags - tags to be added to all content sent

errorHandler - handler to use when an exception occurs during usage, may be null to indicate noop

addressLookup - yields the IP address and socket of the StatsD server

queueSize - the maximum amount of unprocessed messages in the BlockingQueue.

timeout - the timeout in milliseconds for blocking operations. Applies to unix sockets only.

bufferSize - the socket buffer size in bytes. Applies to unix sockets only.

maxPacketSizeBytes - the maximum number of bytes for a message that can be sent

Throws:

StatsDClientException - if the client could not be started

NonBlockingStatsDClient

public NonBlockingStatsDClient(String prefix,
                               int queueSize,
                               String[] constantTags,
                               StatsDClientErrorHandler errorHandler,
                               Callable<SocketAddress> addressLookup,
                               int timeout,
                               int bufferSize,
                               int maxPacketSizeBytes,
                               String entityID)
                        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

constantTags - tags to be added to all content sent

errorHandler - handler to use when an exception occurs during usage, may be null to indicate noop

addressLookup - yields the IP address and socket of the StatsD server

queueSize - the maximum amount of unprocessed messages in the BlockingQueue.

timeout - the timeout in milliseconds for blocking operations. Applies to unix sockets only.

bufferSize - the socket buffer size in bytes. Applies to unix sockets only.

maxPacketSizeBytes - the maximum number of bytes for a message that can be sent

entityID - the entity id value used with an internal tag for tracking client entity. If "entityID=null" the client default the value with the environment variable "DD_ENTITY_ID". If the environment variable is not defined, the internal tag is not added.

Throws:

StatsDClientException - if the client could not be started

Method Detail

createSender

protected StatsDSender createSender(Callable<SocketAddress> addressLookup,
                                    int queueSize,
                                    StatsDClientErrorHandler handler,
                                    DatagramChannel clientChannel,
                                    int maxPacketSizeBytes)

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

close

public void close()

Specified by:

close in interface StatsDClient

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

See Also:

StatsDClient.stop()

count

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

Adjusts the specified counter by a given delta.

This method is non-blocking and is guaranteed not to throw an exception.

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

count

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

Adjusts the specified counter by a given delta.

This method is a DataDog extension, and may not work with other servers.

This method is non-blocking and is guaranteed not to throw an exception.

Specified by:

count in interface StatsDClient

Parameters:

aspect - the name of the counter to adjust

delta - the amount to adjust the counter by

sampleRate - percentage of time metric to be sent

tags - array of tags to be added to the data

count

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

Adjusts the specified counter by a given delta.

This method is non-blocking and is guaranteed not to throw an exception.

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

count

public void count(String aspect,
                  double delta,
                  double sampleRate,
                  String... tags)

Adjusts the specified counter by a given delta.

This method is a DataDog extension, and may not work with other servers.

This method is non-blocking and is guaranteed not to throw an exception.

Specified by:

count in interface StatsDClient

Parameters:

aspect - the name of the counter to adjust

delta - the amount to adjust the counter by

sampleRate - percentage of time metric to be sent

tags - array of tags to be added to the data

incrementCounter

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

Increments the specified counter by one.

This method is non-blocking and is guaranteed not to throw an exception.

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

incrementCounter

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

Increments the specified counter by one.

This method is a DataDog extension, and may not work with other servers.

This method is non-blocking and is guaranteed not to throw an exception.

Specified by:

incrementCounter in interface StatsDClient

Parameters:

aspect - the name of the counter to increment

sampleRate - percentage of time metric to be sent

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

increment

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

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

Specified by:

increment in interface StatsDClient

decrementCounter

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

Decrements the specified counter by one.

This method is non-blocking and is guaranteed not to throw an exception.

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

decrementCounter

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

Decrements the specified counter by one.

This method is a DataDog extension, and may not work with other servers.

This method is non-blocking and is guaranteed not to throw an exception.

Specified by:

decrementCounter in interface StatsDClient

Parameters:

aspect - the name of the counter to decrement

sampleRate - percentage of time metric to be sent

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

decrement

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

Convenience method equivalent to StatsDClient.decrementCounter(String, double, 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.

This method is non-blocking and is guaranteed not to throw an exception.

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

recordGaugeValue

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

Records the latest fixed value for the specified named gauge.

This method is a DataDog extension, and may not work with other servers.

This method is non-blocking and is guaranteed not to throw an exception.

Specified by:

recordGaugeValue in interface StatsDClient

Parameters:

aspect - the name of the gauge

value - the new reading of the gauge

sampleRate - percentage of time metric to be sent

gauge

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

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

Specified by:

gauge in interface StatsDClient

gauge

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

Convenience method equivalent to StatsDClient.recordGaugeValue(String, double, 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.

This method is non-blocking and is guaranteed not to throw an exception.

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

recordGaugeValue

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

Records the latest fixed value for the specified named gauge.

This method is a DataDog extension, and may not work with other servers.

This method is non-blocking and is guaranteed not to throw an exception.

Specified by:

recordGaugeValue in interface StatsDClient

Parameters:

aspect - the name of the gauge

value - the new reading of the gauge

sampleRate - percentage of time metric to be sent

gauge

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

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

Specified by:

gauge in interface StatsDClient

gauge

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

Convenience method equivalent to StatsDClient.recordGaugeValue(String, long, double, 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.

This method is non-blocking and is guaranteed not to throw an exception.

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

recordExecutionTime

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

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

This method is a DataDog extension, and may not work with other servers.

This method is non-blocking and is guaranteed not to throw an exception.

Specified by:

recordExecutionTime in interface StatsDClient

Parameters:

aspect - the name of the timed operation

timeInMs - the time in milliseconds

sampleRate - percentage of time metric to be sent

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

time

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

Convenience method equivalent to StatsDClient.recordExecutionTime(String, long, double, 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.

This method is non-blocking and is guaranteed not to throw an exception.

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

recordHistogramValue

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

Records a value for the specified named histogram.

This method is a DataDog extension, and may not work with other servers.

This method is non-blocking and is guaranteed not to throw an exception.

Specified by:

recordHistogramValue in interface StatsDClient

Parameters:

aspect - the name of the histogram

value - the value to be incorporated in the histogram

sampleRate - percentage of time metric to be sent

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

histogram

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

Convenience method equivalent to StatsDClient.recordHistogramValue(String, double, 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.

This method is non-blocking and is guaranteed not to throw an exception.

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

recordHistogramValue

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

Records a value for the specified named histogram.

This method is a DataDog extension, and may not work with other servers.

This method is non-blocking and is guaranteed not to throw an exception.

Specified by:

recordHistogramValue in interface StatsDClient

Parameters:

aspect - the name of the histogram

value - the value to be incorporated in the histogram

sampleRate - percentage of time metric to be sent

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, long, String[]).

Specified by:

histogram in interface StatsDClient

histogram

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

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

Specified by:

histogram in interface StatsDClient

recordDistributionValue

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

Records a value for the specified named distribution.

This method is non-blocking and is guaranteed not to throw an exception.

This is a beta feature and must be enabled specifically for your organization.

Specified by:

recordDistributionValue in interface StatsDClient

Parameters:

aspect - the name of the distribution

value - the value to be incorporated in the distribution

tags - array of tags to be added to the data

recordDistributionValue

public void recordDistributionValue(String aspect,
                                    double value,
                                    double sampleRate,
                                    String... tags)

Records a value for the specified named distribution.

This method is a DataDog extension, and may not work with other servers.

This method is non-blocking and is guaranteed not to throw an exception.

This is a beta feature and must be enabled specifically for your organization.

Specified by:

recordDistributionValue in interface StatsDClient

Parameters:

aspect - the name of the distribution

value - the value to be incorporated in the distribution

sampleRate - percentage of time metric to be sent

tags - array of tags to be added to the data

distribution

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

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

Specified by:

distribution in interface StatsDClient

distribution

public void distribution(String aspect,
                         double value,
                         double sampleRate,
                         String... tags)

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

Specified by:

distribution in interface StatsDClient

recordDistributionValue

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

Records a value for the specified named distribution.

This method is non-blocking and is guaranteed not to throw an exception.

This is a beta feature and must be enabled specifically for your organization.

Specified by:

recordDistributionValue in interface StatsDClient

Parameters:

aspect - the name of the distribution

value - the value to be incorporated in the distribution

tags - array of tags to be added to the data

recordDistributionValue

public void recordDistributionValue(String aspect,
                                    long value,
                                    double sampleRate,
                                    String... tags)

Records a value for the specified named distribution.

This method is a DataDog extension, and may not work with other servers.

This method is non-blocking and is guaranteed not to throw an exception.

This is a beta feature and must be enabled specifically for your organization.

Specified by:

recordDistributionValue in interface StatsDClient

Parameters:

aspect - the name of the distribution

value - the value to be incorporated in the distribution

sampleRate - percentage of time metric to be sent

tags - array of tags to be added to the data

distribution

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

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

Specified by:

distribution in interface StatsDClient

distribution

public void distribution(String aspect,
                         long value,
                         double sampleRate,
                         String... tags)

Convenience method equivalent to StatsDClient.recordDistributionValue(String, long, double, String[]).

Specified by:

distribution in interface StatsDClient

recordEvent

public void recordEvent(Event event,
                        String... tags)

Records an event

This method is a DataDog extension, and may not work with other servers.

This method is non-blocking and is guaranteed not to throw an exception.

Specified by:

recordEvent in interface StatsDClient

Parameters:

event - The event to record

tags - array of tags to be added to the data

See Also:

http://docs.datadoghq.com/guides/dogstatsd/#events-1

recordServiceCheckRun

public void recordServiceCheckRun(ServiceCheck sc)

Records a run status for the specified named service check.

This method is a DataDog extension, and may not work with other servers.

This method is non-blocking and is guaranteed not to throw an exception.

Specified by:

recordServiceCheckRun in interface StatsDClient

Parameters:

sc - the service check object

serviceCheck

public void serviceCheck(ServiceCheck sc)

Convenience method equivalent to recordServiceCheckRun(ServiceCheck sc).

Specified by:

serviceCheck in interface StatsDClient

recordSetValue

public void recordSetValue(String aspect,
                           String value,
                           String... tags)

Records a value for the specified set. Sets are used to count the number of unique elements in a group. If you want to track the number of unique visitor to your site, sets are a great way to do that.

This method is a DataDog extension, and may not work with other servers.

This method is non-blocking and is guaranteed not to throw an exception.

Specified by:

recordSetValue in interface StatsDClient

Parameters:

aspect - the name of the set

value - the value to track

tags - array of tags to be added to the data

See Also:

http://docs.datadoghq.com/guides/dogstatsd/#sets

volatileAddressResolution

public static Callable<SocketAddress> volatileAddressResolution(String hostname,
                                                                int port)

Create dynamic lookup for the given host name and port.

Parameters:

hostname - the host name of the targeted StatsD server. If the environment variable "DD_AGENT_HOST" is set, this parameter is overwritten by the environment variable value.

port - the port of the targeted StatsD server. If the environment variable "DD_DOGSTATSD_PORT" is set, this parameter is overwritten by the environment variable value.

Returns:

a function to perform the lookup

staticAddressResolution

public static Callable<SocketAddress> staticAddressResolution(String hostname,
                                                              int port)
                                                       throws Exception

Lookup the address for the given host name and cache the result.

Parameters:

hostname - the host name of the targeted StatsD server

port - the port of the targeted StatsD server

Returns:

a function that cached the result of the lookup

Throws:

Exception - if the lookup fails, i.e. UnknownHostException