com.timgroup.statsd.StatsDClient Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of java-statsd-client Show documentation
A tiny library allowing Java applications to communicate with statsd instances easily.
There is a newer version: 3.1.0
package com.timgroup.statsd;

/**
 * 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:
 * 

 *   {@link #incrementCounter} - adds one to the value of the specified named counter
 *   {@link #recordGaugeValue} - records the latest fixed value for the specified named gauge
 *   {@link #recordExecutionTime} - records an execution time in milliseconds for the specified named operation
 *   {@link #recordSetEvent} - records an occurrence of the specified named event
 * 
 *
 * @author Tom Denley
 *
 */
public interface StatsDClient {

    /**
     * Cleanly shut down this StatsD client. This method may throw an exception if
     * the socket cannot be closed.
     */
    void stop();

    /**
     * Adjusts the specified counter by a given delta.
     * 
     * This method is non-blocking and is guaranteed not to throw an exception.
     * 
     * @param aspect
     *     the name of the counter to adjust
     * @param delta
     *     the amount to adjust the counter by
     */
    void count(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.
     *
     * @param aspect
     *     the name of the counter to adjust
     * @param delta
     *     the amount to adjust the counter by
     * @param 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.
     */
    void count(String aspect, long delta, double sampleRate);

    /**
     * Increments the specified counter by one.
     * 
     * This method is non-blocking and is guaranteed not to throw an exception.
     * 
     * @param aspect
     *     the name of the counter to increment
     */
    void incrementCounter(String aspect);

    /**
     * Convenience method equivalent to {@link #incrementCounter(String)}.
     */
    void increment(String aspect);

    /**
     * Decrements the specified counter by one.
     * 
     * This method is non-blocking and is guaranteed not to throw an exception.
     * 
     * @param aspect
     *     the name of the counter to decrement
     */
    void decrementCounter(String aspect);

    /**
     * Convenience method equivalent to {@link #decrementCounter(String)}.
     */
    void decrement(String aspect);

    /**
     * Records the latest fixed value for the specified named gauge.
     * 
     * This method is non-blocking and is guaranteed not to throw an exception.
     * 
     * @param aspect
     *     the name of the gauge
     * @param value
     *     the new reading of the gauge
     */
    void recordGaugeValue(String aspect, long value);

    /**
     * Records a change in the value of the specified named gauge.
     *
     * This method is non-blocking and is guaranteed not to throw an exception.
     *
     * @param aspect
     *     the name of the gauge
     * @param delta
     *     the +/- delta to apply to the gauge
     */
    void recordGaugeDelta(String aspect, long delta);

    /**
     * Convenience method equivalent to {@link #recordGaugeValue(String, long)}.
     */
    void gauge(String aspect, long value);

    /**
     * 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.
     * 
     * @param aspect
     *     the name of the set
     * @param eventName
     *     the value to be added to the set
     */
    void recordSetEvent(String aspect, String eventName);

    /**
     * Convenience method equivalent to {@link #recordSetEvent(String, String)}.
     */
    void set(String aspect, String eventName);

    /**
     * Records an execution time in milliseconds for the specified named operation.
     *
     * This method is non-blocking and is guaranteed not to throw an exception.
     *
     * @param aspect
     *     the name of the timed operation
     * @param timeInMs
     *     the time in milliseconds
     */
    void recordExecutionTime(String aspect, long timeInMs);

    /**
     * Adjusts the specified counter by a given delta.
     *
     * This method is non-blocking and is guaranteed not to throw an exception.
     *
     * @param aspect
     *     the name of the counter to adjust
     * @param delta
     *     the amount to adjust the counter by
     * @param 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.
     */
    void recordExecutionTime(String aspect, long timeInMs, double sampleRate);

    /**
     * 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 {@link System#currentTimeMillis()})
     *
     * This method is non-blocking and is guaranteed not to throw an exception.
     *
     * @param aspect
     *     the name of the timed operation
     * @param timeInMs
     *     the system time, in millis, at the start of the operation that has just completed
     */
    void recordExecutionTimeToNow(String aspect, long systemTimeMillisAtStart);

    /**
     * Convenience method equivalent to {@link #recordExecutionTime(String, long)}.
     */
    void time(String aspect, long value);

}