Publish

1 files changed, 61 insertions, 0 deletions

diff --git a/jdisc_core/src/main/java/com/yahoo/jdisc/Metric.java b/jdisc_core/src/main/java/com/yahoo/jdisc/Metric.java
new file mode 100644
index 00000000000..50b25dbbdf0
--- /dev/null
+++ b/jdisc_core/src/main/java/com/yahoo/jdisc/Metric.java
@@ -0,0 +1,61 @@
+// Copyright 2016 Yahoo Inc. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
+package com.yahoo.jdisc;
+
+import com.google.inject.ProvidedBy;
+import com.google.inject.Provider;
+import com.yahoo.jdisc.application.MetricConsumer;
+import com.yahoo.jdisc.application.MetricProvider;
+
+import java.util.Map;
+
+/**
+ * <p>This interface provides an API for writing metric data to the configured {@link MetricConsumer}. If no {@link
+ * Provider} for the MetricConsumer class has been bound by the application, all calls to this interface are no-ops. The
+ * implementation of this interface uses thread local consumer instances, so as long as the {@link MetricConsumer} is
+ * thread-safe, so is this.</p>
+ *
+ * <p>An instance of this class can be injected anywhere.</p>
+ *
+ * @author <a href="mailto:simon@yahoo-inc.com">Simon Thoresen</a>
+ */
+@ProvidedBy(MetricProvider.class)
+public interface Metric {
+
+    /**
+     * <p>Set a metric value. This is typically used with histogram-type metrics.</p>
+     *
+     * @param key The name of the metric to modify.
+     * @param val The value to assign to the named metric.
+     * @param ctx The context to further describe this entry.
+     */
+    void set(String key, Number val, Context ctx);
+
+    /**
+     * <p>Add to a metric value. This is typically used with counter-type metrics.</p>
+     *
+     * @param key The name of the metric to modify.
+     * @param val The value to add to the named metric.
+     * @param ctx The context to further describe this entry.
+     */
+    void add(String key, Number val, Context ctx);
+
+    /**
+     * <p>Creates a {@link MetricConsumer}-specific {@link Context} object that encapsulates the given properties. The
+     * returned Context object should be passed along every future call to {@link #set(String, Number, Context)} and
+     * {@link #add(String, Number, Context)} where the properties match those given here.</p>
+     *
+     * @param properties The properties to incorporate in the context.
+     * @return The created context.
+     */
+    Context createContext(Map<String, ?> properties);
+
+    /**
+     * <p>Declares the interface for the arbitrary context object to pass to both the {@link
+     * #set(String, Number, Context)} and {@link #add(String, Number, Context)} methods. This is intentionally empty so
+     * that implementations can vary.</p>
+     */
+    interface Context {
+
+    }
+
+}