com.timgroup.statsd

Class NonBlockingStatsDClient

java.lang.Object

com.timgroup.statsd.ConvenienceMethodProvidingStatsDClient

com.timgroup.statsd.NonBlockingStatsDClient

All Implemented Interfaces:

StatsDClient

public final class NonBlockingStatsDClient
extends ConvenienceMethodProvidingStatsDClient

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:

• ConvenienceMethodProvidingStatsDClient.incrementCounter(java.lang.String) - adds one to the value of the specified named counter
• recordGaugeValue(java.lang.String, long) - records the latest fixed value for the specified named gauge
• recordExecutionTime(java.lang.String, long, double) - records an execution time in milliseconds for the specified named operation

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

Constructor Summary

Constructors

Constructor and Description
NonBlockingStatsDClient(java.lang.String prefix, java.lang.String hostname, int port) Create a new StatsD client communicating with a StatsD instance on the specified host and port.
NonBlockingStatsDClient(java.lang.String prefix, java.lang.String hostname, int port, 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(java.lang.String aspect, long delta, double sampleRate) Adjusts the specified counter by a given delta.
void	recordExecutionTime(java.lang.String aspect, long timeInMs, double sampleRate) Records an execution time in milliseconds for the specified named operation.
void	recordGaugeDelta(java.lang.String aspect, double value) Convenience method equivalent to StatsDClient.recordGaugeDelta(String, long) but for double deltas.
void	recordGaugeDelta(java.lang.String aspect, long value) Records a change in the value of the specified named gauge.
void	recordGaugeValue(java.lang.String aspect, double value) Convenience method equivalent to StatsDClient.recordGaugeValue(String, long) but for double values.
void	recordGaugeValue(java.lang.String aspect, long value) Records the latest fixed value for the specified named gauge.
void	recordSetEvent(java.lang.String aspect, java.lang.String eventName) StatsD supports counting unique occurrences of events between flushes, Call this method to records an occurrence of the specified named event.
void	stop() Cleanly shut down this StatsD client.

Methods inherited from class com.timgroup.statsd.ConvenienceMethodProvidingStatsDClient

count, decrement, decrementCounter, gauge, gauge, increment, incrementCounter, recordExecutionTime, recordExecutionTimeToNow, set, time

Methods inherited from class java.lang.Object

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

Constructor Detail

NonBlockingStatsDClient

public NonBlockingStatsDClient(java.lang.String prefix,
                       java.lang.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 (can be null or empty for no prefix)

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

NonBlockingStatsDClient

public NonBlockingStatsDClient(java.lang.String prefix,
                       java.lang.String hostname,
                       int port,
                       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 (can be null or empty for no prefix)

hostname - the host name of the targeted StatsD server

port - the port of the targeted StatsD server

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.

count

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

Adjusts the specified counter by a given delta.

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

Parameters:

aspect - the name of the counter to adjust

delta - the amount to adjust the counter by

sampleRate - the sampling rate being employed. For example, a rate of 0.1 would tell StatsD that this counter is being sent sampled every 1/10th of the time.

recordGaugeValue

public void recordGaugeValue(java.lang.String aspect,
                    long value)

Records the latest fixed value for the specified named gauge.

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

Parameters:

aspect - the name of the gauge

value - the new reading of the gauge

recordGaugeValue

public void recordGaugeValue(java.lang.String aspect,
                    double value)

Description copied from interface: StatsDClient

Convenience method equivalent to StatsDClient.recordGaugeValue(String, long) but for double values.

recordGaugeDelta

public void recordGaugeDelta(java.lang.String aspect,
                    long value)

Description copied from interface: StatsDClient

Records a change in the value of the specified named gauge.

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

Parameters:

aspect - the name of the gauge

value - the +/- delta to apply to the gauge

recordGaugeDelta

public void recordGaugeDelta(java.lang.String aspect,
                    double value)

Description copied from interface: StatsDClient

Convenience method equivalent to StatsDClient.recordGaugeDelta(String, long) but for double deltas.

recordSetEvent

public void recordSetEvent(java.lang.String aspect,
                  java.lang.String eventName)

StatsD supports counting unique occurrences of events between flushes, Call this method to records an occurrence of the specified named event.

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

Parameters:

aspect - the name of the set

eventName - the value to be added to the set

recordExecutionTime

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

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

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

Parameters:

aspect - the name of the timed operation

timeInMs - the time in milliseconds

sampleRate - the sampling rate being employed. For example, a rate of 0.1 would tell StatsD that this timer is being sent sampled every 1/10th of the time, so that it updates its timer_counters appropriately.