Merge pull request #43 from DataDog/joel.barciauskas/add-distribution…

…-support

 Add support for distributions that mirrors histograms

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 2.5 (In progress)
+
+* Added support for new beta feature, global distributions
+
 ## 2.4 / 2017.12.12
 
 Note: Starting from this version the client requires Java7+

README.md

@@ -41,6 +41,8 @@ public class Foo {
     statsd.recordGaugeValue("baz", 0.01); /* DataDog extension: support for floating-point gauges */
     statsd.recordHistogramValue("qux", 15);     /* DataDog extension: histograms */
     statsd.recordHistogramValue("qux", 15.5);   /* ...also floating-point */
+    statsd.recordDistributionValue("qux", 15);     /* DataDog extension: global distributions */
+    statsd.recordDistributionValue("qux", 15.5);   /* ...also floating-point */
 
     ServiceCheck sc = ServiceCheck
           .builder()

src/main/java/com/timgroup/statsd/NoOpStatsDClient.java

@@ -42,6 +42,14 @@ public final class NoOpStatsDClient implements StatsDClient {
     @Override public void recordHistogramValue(String aspect, long value, double sampleRate, String... tags) { }
     @Override public void histogram(String aspect, long value, String... tags) { }
     @Override public void histogram(String aspect, long value, double sampleRate, String... tags) { }
+    @Override public void recordDistributionValue(String aspect, double value, String... tags) { }
+    @Override public void recordDistributionValue(String aspect, double value, double sampleRate, String... tags) { }
+    @Override public void distribution(String aspect, double value, String... tags) { }
+    @Override public void distribution(String aspect, double value, double sampleRate, String... tags) { }
+    @Override public void recordDistributionValue(String aspect, long value, String... tags) { }
+    @Override public void recordDistributionValue(String aspect, long value, double sampleRate, String... tags) { }
+    @Override public void distribution(String aspect, long value, String... tags) { }
+    @Override public void distribution(String aspect, long value, double sampleRate, String... tags) { }
     @Override public void recordEvent(final Event event, final String... tags) { }
     @Override public void recordServiceCheckRun(ServiceCheck sc) { }
     @Override public void serviceCheck(ServiceCheck sc) { }

src/main/java/com/timgroup/statsd/NonBlockingStatsDClient.java

@@ -746,6 +746,101 @@ public void histogram(final String aspect, final long value, final double sample
         recordHistogramValue(aspect, value, sampleRate, tags);
     }
 
+     /**
+     * Records a value for the specified named distribution.
+     *
+     * <p>This method is non-blocking and is guaranteed not to throw an exception.</p>
+     * 
+     * <p>This is a beta feature and must be enabled specifically for your organization.</p>
+     *
+     * @param aspect
+     *     the name of the distribution
+     * @param value
+     *     the value to be incorporated in the distribution
+     * @param tags
+     *     array of tags to be added to the data
+     */
+    @Override
+    public void recordDistributionValue(final String aspect, final double value, final String... tags) {
+        /* Intentionally using %s rather than %f here to avoid
+         * padding with extra 0s to represent precision */
+        send(String.format("%s%s:%s|d%s", prefix, aspect, NUMBER_FORMATTERS.get().format(value), tagString(tags)));
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public void recordDistributionValue(final String aspect, final double value, final double sampleRate, final String... tags) {
+    	if(isInvalidSample(sampleRate)) {
+    		return;
+    	}
+    	  /* Intentionally using %s rather than %f here to avoid
+    	   * padding with extra 0s to represent precision */
+    	send(String.format("%s%s:%s|d|@%f%s", prefix, aspect, NUMBER_FORMATTERS.get().format(value), sampleRate, tagString(tags)));
+    }
+
+    /**
+     * Convenience method equivalent to {@link #recordDistributionValue(String, double, String[])}.
+     */
+    @Override
+    public void distribution(final String aspect, final double value, final String... tags) {
+        recordDistributionValue(aspect, value, tags);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public void distribution(final String aspect, final double value, final double sampleRate, final String... tags) {
+        recordDistributionValue(aspect, value, sampleRate, tags);
+    }
+    /**
+     * Records a value for the specified named distribution.
+     *
+     * <p>This method is non-blocking and is guaranteed not to throw an exception.</p>
+     * 
+     * <p>This is a beta feature and must be enabled specifically for your organization.</p>
+     *
+     * @param aspect
+     *     the name of the distribution
+     * @param value
+     *     the value to be incorporated in the distribution
+     * @param tags
+     *     array of tags to be added to the data
+     */
+    @Override
+    public void recordDistributionValue(final String aspect, final long value, final String... tags) {
+        send(String.format("%s%s:%d|d%s", prefix, aspect, value, tagString(tags)));
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public void recordDistributionValue(final String aspect, final long value, final double sampleRate, final String... tags) {
+    	if(isInvalidSample(sampleRate)) {
+    		return;
+    	}
+        send(String.format("%s%s:%d|d|@%f%s", prefix, aspect, value, sampleRate, tagString(tags)));
+    }
+
+    /**
+     * Convenience method equivalent to {@link #recordDistributionValue(String, long, String[])}.
+     */
+    @Override
+    public void distribution(final String aspect, final long value, final String... tags) {
+        recordDistributionValue(aspect, value, tags);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public void distribution(final String aspect, final long value, final double sampleRate, final String... tags) {
+        recordDistributionValue(aspect, value, sampleRate, tags);
+    }
+
     private String eventMap(final Event event) {
         final StringBuilder res = new StringBuilder("");
 

src/main/java/com/timgroup/statsd/StatsDClient.java

@@ -391,6 +391,102 @@ public interface StatsDClient extends Closeable {
      */
     void histogram(String aspect, long value, double sampleRate, String... tags);
 
+    /**
+     * Records a value for the specified named distribution.
+     *
+     * <p>This method is a DataDog extension, and may not work with other servers.</p>
+     *
+     * <p>This method is non-blocking and is guaranteed not to throw an exception.</p>
+     *
+     * <p>This is a beta feature and must be enabled specifically for your organization.</p>
+     * 
+     * @param aspect
+     *     the name of the distribution 
+     * @param value
+     *     the value to be incorporated in the distribution
+     * @param tags
+     *     array of tags to be added to the data
+     */
+    void recordDistributionValue(String aspect, double value, String... tags);
+
+    /**
+     * Records a value for the specified named distribution.
+     *
+     * <p>This method is a DataDog extension, and may not work with other servers.</p>
+     *
+     * <p>This method is non-blocking and is guaranteed not to throw an exception.</p>
+     *
+     * <p>This is a beta feature and must be enabled specifically for your organization.</p>
+     * 
+     * @param aspect
+     *     the name of the distribution 
+     * @param value
+     *     the value to be incorporated in the distribution
+     * @param sampleRate    
+     *     percentage of time metric to be sent
+     * @param tags
+     *     array of tags to be added to the data
+     */
+    void recordDistributionValue(String aspect, double value, double sampleRate, String... tags);
+
+    /**
+     * Convenience method equivalent to {@link #recordDistributionValue(String, double, String[])}.
+     */
+    void distribution(String aspect, double value, String... tags);
+
+    /**
+     * Convenience method equivalent to {@link #recordDistributionValue(String, double, double, String[])}.
+     */
+    void distribution(String aspect, double value, double sampleRate, String... tags);
+
+    /**
+     * Records a value for the specified named distribution.
+     *
+     * <p>This method is a DataDog extension, and may not work with other servers.</p>
+     *
+     * <p>This method is non-blocking and is guaranteed not to throw an exception.</p>
+     *
+     * <p>This is a beta feature and must be enabled specifically for your organization.</p>
+     * 
+     * @param aspect
+     *     the name of the distribution
+     * @param value
+     *     the value to be incorporated in the distribution
+     * @param tags
+     *     array of tags to be added to the data
+     */
+    void recordDistributionValue(String aspect, long value, String... tags);
+
+    /**
+     * Records a value for the specified named distribution.
+     *
+     * <p>This method is a DataDog extension, and may not work with other servers.</p>
+     *
+     * <p>This method is non-blocking and is guaranteed not to throw an exception.</p>
+     *
+     * <p>This is a beta feature and must be enabled specifically for your organization.</p>
+     * 
+     * @param aspect
+     *     the name of the distribution
+     * @param value
+     *     the value to be incorporated in the distribution
+     * @param sampleRate
+     * 		percentage of time metric to be sent
+     * @param tags
+     *     array of tags to be added to the data
+     */
+    void recordDistributionValue(String aspect, long value, double sampleRate, String... tags);
+
+    /**
+     * Convenience method equivalent to {@link #recordDistributionValue(String, long, String[])}.
+     */
+    void distribution(String aspect, long value, String... tags);
+
+    /**
+     * Convenience method equivalent to {@link #recordDistributionValue(String, long, double, String[])}.
+     */
+    void distribution(String aspect, long value, double sampleRate, String... tags);
+
     /**
      * Records an event
      *

src/test/java/com/timgroup/statsd/NonBlockingStatsDClientTest.java

@@ -293,6 +293,65 @@ public void clear() {
         assertThat(server.messagesReceived(), contains("my.prefix.myhistogram:0.423|h|@1.000000|#baz,foo:bar"));
     }
 
+    @Test(timeout=5000L) public void
+    sends_distribtuion_to_statsd() throws Exception {
+
+        client.recordDistributionValue("mydistribution", 423);
+        server.waitForMessage();
+
+        assertThat(server.messagesReceived(), contains("my.prefix.mydistribution:423|d"));
+    }
+
+    @Test(timeout=5000L) public void
+    sends_double_distribution_to_statsd() throws Exception {
+
+
+        client.recordDistributionValue("mydistribution", 0.423);
+        server.waitForMessage();
+
+        assertThat(server.messagesReceived(), contains("my.prefix.mydistribution:0.423|d"));
+    }
+
+    @Test(timeout=5000L) public void
+    sends_distribution_to_statsd_with_tags() throws Exception {
+
+
+        client.recordDistributionValue("mydistribution", 423, "foo:bar", "baz");
+        server.waitForMessage();
+
+        assertThat(server.messagesReceived(), contains("my.prefix.mydistribution:423|d|#baz,foo:bar"));
+    }
+
+    @Test(timeout=5000L) public void
+    sends_distribution_with_sample_rate_to_statsd_with_tags() throws Exception {
+
+
+        client.recordDistributionValue("mydistribution", 423, 1, "foo:bar", "baz");
+        server.waitForMessage();
+
+        assertThat(server.messagesReceived(), contains("my.prefix.mydistribution:423|d|@1.000000|#baz,foo:bar"));
+    }
+
+    @Test(timeout=5000L) public void
+    sends_double_distribution_to_statsd_with_tags() throws Exception {
+
+
+        client.recordDistributionValue("mydistribution", 0.423, "foo:bar", "baz");
+        server.waitForMessage();
+
+        assertThat(server.messagesReceived(), contains("my.prefix.mydistribution:0.423|d|#baz,foo:bar"));
+    }
+
+    @Test(timeout=5000L) public void
+    sends_double_distribution_with_sample_rate_to_statsd_with_tags() throws Exception {
+
+
+        client.recordDistributionValue("mydistribution", 0.423, 1, "foo:bar", "baz");
+        server.waitForMessage();
+
+        assertThat(server.messagesReceived(), contains("my.prefix.mydistribution:0.423|d|@1.000000|#baz,foo:bar"));
+    }
+
     @Test(timeout=5000L) public void
     sends_timer_to_statsd() throws Exception {