com.timgroup.statsd

Interface StatsDClient

All Known Implementing Classes:

ConvenienceMethodProvidingStatsDClient, NonBlockingStatsDClient, NoOpStatsDClient

public interface StatsDClient

Describes a client connection to a StatsD server, which may be used to post metrics in the form of counters, timers, and gauges.

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

• 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) - records an execution time in milliseconds for the specified named operation
• recordSetEvent(java.lang.String, java.lang.String) - records an occurrence of the specified named event

Author:

Tom Denley

Method Summary

Methods

Modifier and Type	Method and Description
void	count(java.lang.String aspect, long delta) Adjusts the specified counter by a given delta.
void	count(java.lang.String aspect, long delta, double sampleRate) Adjusts the specified counter by a given delta.
void	decrement(java.lang.String aspect) Convenience method equivalent to decrementCounter(String).
void	decrementCounter(java.lang.String aspect) Decrements the specified counter by one.
void	gauge(java.lang.String aspect, long value) Convenience method equivalent to recordGaugeValue(String, long).
void	increment(java.lang.String aspect) Convenience method equivalent to incrementCounter(String).
void	incrementCounter(java.lang.String aspect) Increments the specified counter by one.
void	recordExecutionTime(java.lang.String aspect, long timeInMs) Records an execution time in milliseconds for the specified named operation.
void	recordExecutionTime(java.lang.String aspect, long timeInMs, double sampleRate) Adjusts the specified counter by a given delta.
void	recordExecutionTimeToNow(java.lang.String aspect, long systemTimeMillisAtStart) Records an execution time in milliseconds for the specified named operation.
void	recordGaugeDelta(java.lang.String aspect, long delta) Records a change in the value of the specified named gauge.
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	set(java.lang.String aspect, java.lang.String eventName) Convenience method equivalent to recordSetEvent(String, String).
void	stop() Cleanly shut down this StatsD client.
void	time(java.lang.String aspect, long value) Convenience method equivalent to recordExecutionTime(String, long).

Method Detail

stop

void stop()

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

count

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

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

count

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.

incrementCounter

void incrementCounter(java.lang.String aspect)

Increments the specified counter by one.

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

Parameters:

aspect - the name of the counter to increment

increment

void increment(java.lang.String aspect)

Convenience method equivalent to incrementCounter(String).

decrementCounter

void decrementCounter(java.lang.String aspect)

Decrements the specified counter by one.

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

Parameters:

aspect - the name of the counter to decrement

decrement

void decrement(java.lang.String aspect)

Convenience method equivalent to decrementCounter(String).

recordGaugeValue

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

recordGaugeDelta

void recordGaugeDelta(java.lang.String aspect,
                    long delta)

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

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

gauge

void gauge(java.lang.String aspect,
         long value)

Convenience method equivalent to recordGaugeValue(String, long).

recordSetEvent

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

set

void set(java.lang.String aspect,
       java.lang.String eventName)

Convenience method equivalent to recordSetEvent(String, String).

recordExecutionTime

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

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

recordExecutionTime

void recordExecutionTime(java.lang.String aspect,
                       long timeInMs,
                       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 timer is being sent sampled every 1/10th of the time, so that it updates its timer_counters appropriately.

recordExecutionTimeToNow

void recordExecutionTimeToNow(java.lang.String aspect,
                            long systemTimeMillisAtStart)

Records an execution time in milliseconds for the specified named operation. The execution time is calculated as the delta between the specified start time and the current system time (using System.currentTimeMillis())

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

Parameters:

aspect - the name of the timed operation

timeInMs - the system time, in millis, at the start of the operation that has just completed

time

void time(java.lang.String aspect,
        long value)

Convenience method equivalent to recordExecutionTime(String, long).