COMMON-1195 : support posting events

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

@@ -0,0 +1,166 @@
+package com.timgroup.statsd;
+
+import java.util.Date;
+
+/**
+ * An event to send
+ * @see <a href="http://docs.datadoghq.com/guides/dogstatsd/#events">http://docs.datadoghq.com/guides/dogstatsd/#events</a>
+ */
+public class Event {
+    private String title;
+    private String text;
+    private long millisSinceEpoch = -1;
+    private String hostname;
+    private String aggregationKey;
+    private String priority;
+    private String sourceTypeName;
+    private String alertType;
+
+    public String getTitle() {
+        return title;
+    }
+
+    public String getText() {
+        return text;
+    }
+
+    /**
+     * @return -1 if not set
+     */
+    public long getMillisSinceEpoch() {
+        return millisSinceEpoch;
+    }
+
+    public String getHostname() {
+        return hostname;
+    }
+
+    public String getAggregationKey() {
+        return aggregationKey;
+    }
+
+    public String getPriority() {
+        return priority;
+    }
+
+    public String getSourceTypeName() {
+        return sourceTypeName;
+    }
+
+    public String getAlertType() {
+        return alertType;
+    }
+
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    private Event(){}
+
+    public enum Priority {
+        LOW, NORMAL
+    }
+
+    public enum AlertType {
+        ERROR, WARNING, INFO, SUCCESS
+    }
+
+    @SuppressWarnings({"AccessingNonPublicFieldOfAnotherObject", "PrivateMemberAccessBetweenOuterAndInnerClass", "ParameterHidesMemberVariable"})
+    public static class Builder {
+        private final Event event = new Event();
+        private Builder() {}
+
+        public Event build() {
+            if ((event.title == null) || event.title.isEmpty()) {
+                throw new IllegalStateException("event title must be set");
+            }
+            if ((event.text == null) || event.text.isEmpty()) {
+                throw new IllegalStateException("event text must be set");
+            }
+            return event;
+        }
+
+        /**
+         * @param title
+         *     Event title ; mandatory
+         */
+        public Builder withTitle(final String title) {
+            event.title = title;
+            return this;
+        }
+
+        /**
+         * @param text
+         *     Event text ; supports line breaks ; mandatory
+         */
+        public Builder withText(final String text) {
+            event.text = text;
+            return this;
+        }
+
+        /**
+         * @param date
+         *     Assign a timestamp to the event ; Default: none (Default is the current Unix epoch timestamp when not sent)
+         */
+        public Builder withDate(final Date date) {
+            event.millisSinceEpoch = date.getTime();
+            return this;
+        }
+
+        /**
+         * @param millisSinceEpoch
+         *     Assign a timestamp to the event ; Default: none (Default is the current Unix epoch timestamp when not sent)
+         */
+        public Builder withDate(final long millisSinceEpoch) {
+            event.millisSinceEpoch = millisSinceEpoch;
+            return this;
+        }
+
+        /**
+         * @param hostname
+         *     Assign a hostname to the event ; Default: none
+         */
+        public Builder withHostname(final String hostname) {
+            event.hostname = hostname;
+            return this;
+        }
+
+        /**
+         * @param aggregationKey
+         *     Assign an aggregation key to the event, to group it with some others ; Default: none
+         */
+        public Builder withAggregationKey(final String aggregationKey) {
+            event.aggregationKey = aggregationKey;
+            return this;
+        }
+
+        /**
+         * @param priority
+         *     Can be "normal" or "low" ; Default: "normal"
+         */
+        public Builder withPriority(final Priority priority) {
+            //noinspection StringToUpperCaseOrToLowerCaseWithoutLocale
+            event.priority = priority.name().toLowerCase();
+            return this;
+        }
+
+        /**
+         * @param sourceTypeName
+         *     Assign a source type to the event ; Default: none
+         */
+        public Builder withSourceTypeName(final String sourceTypeName) {
+            event.sourceTypeName = sourceTypeName;
+            return this;
+        }
+
+        /**
+         * @param alertType
+         *     Can be "error", "warning", "info" or "success" ; Default: "info"
+         */
+        public Builder withAlertType(final AlertType alertType) {
+            //noinspection StringToUpperCaseOrToLowerCaseWithoutLocale
+            event.alertType = alertType.name().toLowerCase();
+            return this;
+        }
+    }
+}

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

@@ -24,4 +24,5 @@ public final class NoOpStatsDClient implements StatsDClient {
     @Override public void histogram(String aspect, double value, String... tags) { }
     @Override public void recordHistogramValue(String aspect, long value, String... tags) { }
     @Override public void histogram(String aspect, long value, String... tags) { }
+    @Override public void recordEvent(final Event event, final String... tags) { }
 }

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

@@ -28,6 +28,7 @@
  *   <li>{@link #recordGaugeValue} - records the latest fixed value for the specified named gauge</li>
  *   <li>{@link #recordExecutionTime} - records an execution time in milliseconds for the specified named operation</li>
  *   <li>{@link #recordHistogramValue} - records a value, to be tracked with average, maximum, and percentiles</li>
+ *   <li>{@link #recordEvent} - records an event</li>
  * </ul>
  * 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
@@ -437,6 +438,59 @@ public void histogram(String aspect, long value, String... tags) {
         recordHistogramValue(aspect, value, tags);
     }
 
+    private String eventMap(final Event event) {
+        final StringBuilder res = new StringBuilder("");
+
+        final long millisSinceEpoch = event.getMillisSinceEpoch();
+        if (millisSinceEpoch != -1) {
+            res.append("|d:").append(millisSinceEpoch / 1000);
+        }
+
+        final String hostname = event.getHostname();
+        if (hostname != null) {
+            res.append("|h:").append(hostname);
+        }
+
+        final String aggregationKey = event.getAggregationKey();
+        if (aggregationKey != null) {
+            res.append("|k:").append(aggregationKey);
+        }
+
+        final String priority = event.getPriority();
+        if (priority != null) {
+            res.append("|p:").append(priority);
+        }
+
+        final String alertType = event.getAlertType();
+        if (alertType != null) {
+            res.append("|t:").append(alertType);
+        }
+
+        return res.toString();
+    }
+
+    /**
+     * Records an event
+     *
+     * <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>
+     *
+     * @param event
+     *     The event to record
+     * @param tags
+     *     array of tags to be added to the data
+     *
+     * @see <a href="http://docs.datadoghq.com/guides/dogstatsd/#events-1">http://docs.datadoghq.com/guides/dogstatsd/#events-1</a>
+     */
+    @Override
+    public void recordEvent(final Event event, final String... tags) {
+        final String title = prefix + event.getTitle();
+        final String text = event.getText();
+        send(String.format("_e{%d,%d}:%s|%s%s%s",
+                title.length(), text.length(), title, text, eventMap(event), tagString(tags)));
+    }
+
     private void send(String message) {
         queue.offer(message);
     }

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

@@ -178,4 +178,19 @@ public interface StatsDClient {
      */
     void histogram(String aspect, long value, String... tags);
 
+    /**
+     * Records an event
+     *
+     * <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>
+     *
+     * @param event
+     *     The event to record
+     * @param tags
+     *     array of tags to be added to the data
+     *
+     * @see <a href="http://docs.datadoghq.com/guides/dogstatsd/#events-1">http://docs.datadoghq.com/guides/dogstatsd/#events-1</a>
+     */
+    void recordEvent(Event event, String... tags);
 }

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

@@ -0,0 +1,83 @@
+package com.timgroup.statsd;
+
+import org.junit.Test;
+
+import java.util.Date;
+
+import static org.junit.Assert.assertEquals;
+
+public class EventTest {
+    @Test
+    public void builds() {
+        final Event event = Event.builder()
+                .withTitle("title1")
+                .withText("text1")
+                .withDate(1234)
+                .withHostname("host1")
+                .withPriority(Event.Priority.LOW)
+                .withAggregationKey("key1")
+                .withAlertType(Event.AlertType.ERROR)
+                .build();
+
+        assertEquals("title1", event.getTitle());
+        assertEquals("text1", event.getText());
+        assertEquals(1234, event.getMillisSinceEpoch());
+        assertEquals("host1", event.getHostname());
+        assertEquals("low", event.getPriority());
+        assertEquals("key1", event.getAggregationKey());
+        assertEquals("error", event.getAlertType());
+    }
+
+    @Test
+    public void builds_with_defaults() {
+        final Event event = Event.builder()
+                .withTitle("title1")
+                .withText("text1")
+                .build();
+
+        assertEquals("title1", event.getTitle());
+        assertEquals("text1", event.getText());
+        assertEquals(-1, event.getMillisSinceEpoch());
+        assertEquals(null, event.getHostname());
+        assertEquals(null, event.getPriority());
+        assertEquals(null, event.getAggregationKey());
+        assertEquals(null, event.getAlertType());
+    }
+
+    @Test (expected = IllegalStateException.class)
+    public void fails_without_title() {
+        Event.builder().withText("text1")
+                .withDate(1234)
+                .withHostname("host1")
+                .withPriority(Event.Priority.LOW)
+                .withAggregationKey("key1")
+                .withAlertType(Event.AlertType.ERROR)
+                .build();
+    }
+
+    @Test (expected = IllegalStateException.class)
+    public void fails_without_text() {
+        Event.builder().withTitle("title1")
+                .withDate(1234)
+                .withHostname("host1")
+                .withPriority(Event.Priority.LOW)
+                .withAggregationKey("key1")
+                .withAlertType(Event.AlertType.ERROR)
+                .build();
+    }
+
+    @Test
+    public void builds_with_date() {
+        final long expectedMillis = 1234567000;
+        final Date date = new Date(expectedMillis);
+        final Event event = Event.builder()
+                .withTitle("title1")
+                .withText("text1")
+                .withDate(date)
+                .build();
+
+        assertEquals("title1", event.getTitle());
+        assertEquals("text1", event.getText());
+        assertEquals(expectedMillis, event.getMillisSinceEpoch());
+    }
+}