Updated documentation and added passing instant to collectors

README.md

@@ -589,13 +589,82 @@ will match the type so if you define both a LongCounter and a DoubleCounter it w
 know to grab the LongCounter as it inherits from LongCollector.  The following
 collectors are all in the `org.kairosdb.metrics4j.collectors.impl` package.
 
+Here is an example of defining a LongCounter:
+```hocon
+metrics4j {
+  ...
+  collectors: {
+    myLongCounter: { #This is your name for the collector that you can reference when assigning the collector
+      _class: "org.kairosdb.metrics4j.collectors.impl.LongCounter"
+      reset: true  #Many collectors have options that you can set to change behavior
+    }
+  }
+  ...
+}
+```
+
+#### BagCollector
+This collector does not do any aggregation.  Whatever value was put into the collector
+is reported using the time of the put or the Instant if one was provided.
+BagCollector can collect Long, Double and String values.
+
+#### Chained Collectors
+There is a chain collector for each type of data: ChainedDoubleCollector, 
+ChainedDurationCollector, ChainedLongCollector, ChainedStringCollector, ChainedTimeCollector
+
+The chain collector lets you put data into multiple collectors where each one is 
+reported.
+
+For example lets say you have a value that you want to both count and report
+the max value from
+```hocon
+metrics4j {
+  ...
+  collectors: {
+    myLongCounter: { 
+      _class: "org.kairosdb.metrics4j.collectors.impl.LongCounter"
+    }
+    myMax: {
+      _class: "org.kairosdb.metrics4j.collectors.impl.MaxLongGuage"
+    }
+    myChainCollector: { 
+      _class: "org.kairosdb.metrics4j.collectors.impl.ChainedLongCollector"
+      collectors: ["myLongCounter", "myMax"]
+      prefixes: ["count.", "max."] #prefix to identify each metric
+    }
+  }
+  ...
+}
+```
+
+The prefixes are applied to the collectors that are defined respectively.  If the 
+metric being reported was `myMetric.value`, the chain collector would report two
+values `myMetric.count.value` and `myMetric.max.value`.  The prefix is applied
+to the last part of the metric.
+
+* _collectors:_ List of collectors to chain together
+* _prefixes:_ Prefix to add to each collector respectively
+
 #### DoubleCounter
 Counts up double values to be reported.  The counter can be reset when values are reported
 by setting reset: true in the conf
 
 * _reset:_ (true/false), when true the counter resets after reporting
 * _report-zero:_ (true/false), when set to false will not report zero values
 
+#### DoubleGauge
+Simple gauge that reports the most recently received value.
+
+* _reset:_ (true/false), when true the gauge sets to zero after reporting
+
+#### LastTime
+LastTime collects Duration metrics and when reporting it simply reports the last
+Duration it received.  The Duration is cleared once it is reported so it is
+only reported once.
+
+* _report-unit:_ (NANOS, MICROS, MILLIS, SECONDS, MINUTES, HOURS, DAYS), set
+  the unites values are reported in
+
 #### LongCounter
 Counts up long values to be reported.  The counter can be reset when values are reported
 by setting reset: true in the conf
@@ -613,10 +682,16 @@ Extends LongGauge and only stores and reports the max value over the reporting p
 
 * _reset:_ (true/false), when true the gauge sets to zero after reporting
 
-#### DoubleGauge
-Simple gauge that reports the most recently received value.
+#### NullCollector
+If you are familiar with /dev/null, this is the same concept.  A way of turning
+off certain metrics.
 
-* _reset:_ (true/false), when true the gauge sets to zero after reporting
+#### PutCounter
+Counts the number of times the put method is called on a collector.  Can be used 
+with any data type.
+
+* _reset:_ (true/false), when true the counter resets after reporting
+* _report-zero:_ (true/false), when set to false will not report zero values
 
 #### SimpleStats
 This reports the min, max, sum, count and avg for the set of values received since
@@ -638,6 +713,29 @@ the unites values are reported in
 No aggregation is done in this collector.  All strings are reported with the time
 they were received.
 
+#### TimeDelta
+This records the difference between now (computers local clock) and the timestamp
+provided.  The deltas are recorded as a SimpleTimerMetric
+
+Takes the same parameters as SimpleTimerMetric
+
+#### TimestampCounter
+This collector records a count of timestamps during a configurable amount of time.
+The initial use of this collector was to count events going in and out of an event
+system.  The idea is to count all events that occur in a bucket of time and report
+them using a timestamp within that bucket.
+
+The default configuration can handle the same timestamp (rounded to the minute)
+being reported for just short of 2 weeks (13 ish days) before potentially overwriting
+the same timestamp when reporting data.
+
+Basically a timestamp (rounded to the minute) can be counted and reported for about 2 weeks
+each time it reports it will use a slightly different timestamp so as to not overwrite
+previous counts
+
+For a detail description of how this works see: 
+https://github.com/kairosdb/metrics4j/wiki/TimestampCounter
+
 ### Formatters
 A formatter can change the name to your liking ie. underscore vs period
 in the name.

metrics4j/src/main/java/org/kairosdb/metrics4j/MetricSourceManager.java

@@ -24,6 +24,8 @@
 import java.util.function.DoubleSupplier;
 import java.util.function.LongSupplier;
 
+import static java.util.Objects.requireNonNull;
+
 /**
  Need to put methods to set various components programmatically.
 
@@ -76,12 +78,12 @@ public static MetricConfig getMetricConfig()
 		return s_metricConfig;
 	}
 
-	public static void registerMetricCollector(MetricCollector collector)
+	/*public static void registerMetricCollector(MetricCollector collector)
 	{
 		ArgKey key = new CustomArgKey(collector);
 
-		//getMetricConfig().getContext().assignCollector(key, collector, new HashMap<>(), new HashMap<>(), null);
-	}
+		getMetricConfig().getContext().assignCollector(key, collector, new HashMap<>(), new HashMap<>(), null);
+	}*/
 
 	public static <T> T getSource(Class<T> tClass)
 	{
@@ -102,6 +104,7 @@ public static <T> T getSource(Class<T> tClass)
 
 		//todo need to do some validation on tClass, makes ure all methods only take strings and are annotated with Keys
 
+		requireNonNull(tClass, "Source class object cannot be null");
 		InvocationHandler handler = s_invocationMap.computeIfAbsent(tClass, (klass) -> {
 			MetricConfig metricConfig = getMetricConfig();
 			if (metricConfig.isDumpMetrics())
@@ -165,8 +168,22 @@ private static TagKey buildTagKey(Map<String, String> tags)
 		return builder.build();
 	}
 
+	/**
+	 In some cases it is more helpful to have the metrics code call into your code
+	 to gather the metric or state of the system at the time of collection.  This
+	 method allows you to artificially create a MetricCollector that will be called
+	 when metrics are collected to be reported
+	 @param className The class name to identify this collector for configuration purposes.
+	 @param methodName The method name to identify this collector for configuration purposes.
+	 @param tags Tags associated with this collector
+	 @param help Help text for this collector
+	 @param collector A instance that implements MetricCollector to be called when collecting metrics.
+	 */
 	public static void addSource(String className, String methodName, Map<String, String> tags, String help, MetricCollector collector)
 	{
+		requireNonNull(className, "className cannot be null");
+		requireNonNull(methodName, "methodName cannot be null");
+		requireNonNull(collector, "collector cannot be null");
 		ArgKey key = new LambdaArgKey(className, methodName);
 		MetricConfig metricConfig = getMetricConfig();
 
@@ -195,11 +212,27 @@ public static void addSource(String className, String methodName, Map<String, St
 		collection.addCollector(buildTagKey(tags), collector);
 	}
 
+	/**
+	 A helper method that lets you pass a lambda function as the MetricCollector see {@link #addSource(String, String, Map, String, MetricCollector) addSource} method.
+	 @param className The class name to identify this collector for configuration purposes.
+	 @param methodName The method name to identify this collector for configuration purposes.
+	 @param tags Tags associated with this collector
+	 @param help Help text for this collector
+	 @param supplier Lambda function that returns a long value.
+	 */
 	public static void addSource(String className, String methodName, Map<String, String> tags, String help, LongSupplier supplier)
 	{
 		addSource(className, methodName, tags, help, new LongLambdaCollectorAdaptor(supplier));
 	}
 
+	/**
+	 A helper method that lets you pass a lambda function as the MetricCollector see {@link #addSource(String, String, Map, String, MetricCollector) addSource} method.
+	 @param className The class name to identify this collector for configuration purposes.
+	 @param methodName The method name to identify this collector for configuration purposes.
+	 @param tags Tags associated with this collector
+	 @param help Help text for this collector
+	 @param supplier Lambda function that returns a double value.
+	 */
 	public static void addSource(String className, String methodName, Map<String, String> tags, String help, DoubleSupplier supplier)
 	{
 		addSource(className, methodName, tags, help, new DoubleLambdaCollectorAdaptor(supplier));

metrics4j/src/main/java/org/kairosdb/metrics4j/collectors/DoubleCollector.java

@@ -1,6 +1,23 @@
 package org.kairosdb.metrics4j.collectors;
 
+import java.time.Instant;
+
 public interface DoubleCollector extends Collector
 {
+	/**
+	 Place a double value into the collector to be reported.
+	 The actual value reported is determined by the collector implementation
+	 that is configured for this source.
+	 @param value Value to be reported.
+	 */
 	void put(double value);
+
+	/**
+	 Place a double value and associated timestamp into the collector to be reported.
+	 The actual value and time reported is determined by the collector implementation
+	 that is configured for this source.
+	 @param time Suggested timestamp to use when reporting.
+	 @param value Value to be reported.
+	 */
+	void put(Instant time, double value);
 }

metrics4j/src/main/java/org/kairosdb/metrics4j/collectors/DurationCollector.java

@@ -3,6 +3,7 @@
 import org.kairosdb.metrics4j.collectors.helpers.BlockTimer;
 
 import java.time.Duration;
+import java.time.Instant;
 import java.util.concurrent.Callable;
 
 /**
@@ -11,7 +12,22 @@
  */
 public interface DurationCollector extends Collector
 {
+	/**
+	 Place a Duration value into the collector to be reported.
+	 The actual value reported is determined by the collector implementation
+	 that is configured for this source.
+	 @param duration Value to be reported.
+	 */
 	void put(Duration duration);
+
+	/**
+	 Place a Duration value and associated timestamp into the collector to be reported.
+	 The actual value and time reported is determined by the collector implementation
+	 that is configured for this source.
+	 @param time Suggested timestamp to use when reporting.
+	 @param duration Value to be reported.
+	 */
+	void put(Instant time, Duration duration);
 	<T> T timeEx(Callable<T> callable) throws Exception;
 	<T> T time(TimeCallable<T> callable);
 	BlockTimer time();

metrics4j/src/main/java/org/kairosdb/metrics4j/collectors/LongCollector.java

@@ -1,6 +1,23 @@
 package org.kairosdb.metrics4j.collectors;
 
+import java.time.Instant;
+
 public interface LongCollector extends Collector
 {
+	/**
+	 Place a long value into the collector to be reported.
+	 The actual value reported is determined by the collector implementation
+	 that is configured for this source.
+	 @param value Value to be reported.
+	 */
 	void put(long value);
+
+	/**
+	 Place a long value and associated timestamp into the collector to be reported.
+	 The actual value and time reported is determined by the collector implementation
+	 that is configured for this source.
+	 @param time Suggested timestamp to use when reporting.
+	 @param value Value to be reported.
+	 */
+	void put(Instant time, long value);
 }

metrics4j/src/main/java/org/kairosdb/metrics4j/collectors/StringCollector.java

@@ -1,6 +1,23 @@
 package org.kairosdb.metrics4j.collectors;
 
+import java.time.Instant;
+
 public interface StringCollector extends Collector
 {
+	/**
+	 Place a String value into the collector to be reported.
+	 The actual value reported is determined by the collector implementation
+	 that is configured for this source.
+	 @param value Value to be reported.
+	 */
 	void put(String value);
+
+	/**
+	 Place a double value and associated timestamp into the collector to be reported.
+	 The actual value and time reported is determined by the collector implementation
+	 that is configured for this source.
+	 @param time Suggested timestamp to use when reporting.
+	 @param value Value to be reported.
+	 */
+	void put(Instant time, String value);
 }

metrics4j/src/main/java/org/kairosdb/metrics4j/collectors/TimeCollector.java

@@ -8,5 +8,20 @@
  */
 public interface TimeCollector extends Collector
 {
-	void put(Instant time);
+	/**
+	 Place a double value into the collector to be reported.
+	 The actual value reported is determined by the collector implementation
+	 that is configured for this source.
+	 @param value Value to be reported.
+	 */
+	void put(Instant value);
+
+	/**
+	 Place a double value and associated timestamp into the collector to be reported.
+	 The actual value and time reported is determined by the collector implementation
+	 that is configured for this source.
+	 @param time Suggested timestamp to use when reporting.
+	 @param value Value to be reported.
+	 */
+	void put(Instant time, Instant value);
 }

metrics4j/src/main/java/org/kairosdb/metrics4j/collectors/helpers/ChainedCollector.java

@@ -13,6 +13,10 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ ChainedCollector lets you report metrics to more than one collector.
+ @param <C>
+ */
 @ToString
 @EqualsAndHashCode
 public abstract class ChainedCollector<C extends Collector> extends Cloneable implements Collector

metrics4j/src/main/java/org/kairosdb/metrics4j/collectors/impl/ChainedDoubleCollector.java

@@ -5,6 +5,9 @@
 import org.kairosdb.metrics4j.collectors.helpers.ChainedCollector;
 import org.kairosdb.metrics4j.configuration.ConfigurationException;
 
+import java.time.Instant;
+
+
 public class ChainedDoubleCollector extends ChainedCollector<DoubleCollector> implements DoubleCollector
 {
 	@Override
@@ -16,6 +19,15 @@ public void put(double value)
 		}
 	}
 
+	@Override
+	public void put(Instant time, double value)
+	{
+		for (PrefixMetricReporter<DoubleCollector> chainedCollector : m_chainedCollectors)
+		{
+			chainedCollector.getCollector().put(time, value);
+		}
+	}
+
 	@Override
 	public Collector clone()
 	{