Fixed bug in jmx reporter plugin not setting metric type context for …

…otel sink plugin. Updated documentation for otel sink

README.md

@@ -6,11 +6,18 @@
 - [Section 1 (Developer)](#section-1--developer-)
   * [Using the library](#using-the-library)
   * [Different ways to report metrics](#different-ways-to-report-metrics)
+    + [Duration Helpers](#duration-helpers)
+    + [Annotations](#annotations)
+      - [Reported](#reported)
+      - [Snapshot](#snapshot)
+  * [Setting Tags on a Thread](#setting-tags-on-a-thread)
   * [Testing with the library](#testing-with-the-library)
 - [Section 2 (Admin)](#section-2--admin-)
   * [The Config Files](#the-config-files)
   * [Configuration](#configuration)
     - [Configuration Parameters](#configuration-parameters)
+      * [Java System Properties](#java-system-properties)
+      * [Environment Variables](#environment-variables)
     + [Sources](#sources)
       + [Overrides](#overrides)
       + [Metric Name](#metric-name)
@@ -19,14 +26,17 @@
       * [Getting available sources](#getting-available-sources)
       * [Disabling sources](#disabling-sources)
     + [Sinks](#sinks)
-      - [Slf4JMetricSink](#slf4jmetricsink)
-      - [TelnetSink](#telnetsink)
-      - [GraphitePlaintextSink](#graphiteplaintextsink)
-      - [InfluxSink](#influxsink)
-      - [PrometheusSink](#prometheussink)
-      - [KairosSink](#kairossink)
-      - [TimescaleDBSink](#timescaledbsink)
-      - [StatsDTCPSink](#statsdtcpsink)
+      - [Internal](#internal)
+        * [Slf4JMetricSink](#slf4jmetricsink)
+        * [TelnetSink](#telnetsink)
+        * [GraphitePlaintextSink](#graphiteplaintextsink)
+        * [StatsDTCPSink](#statsdtcpsink)
+      - [External](#external)
+        * [InfluxSink](#influxsink)
+        * [PrometheusSink](#prometheussink)
+        * [KairosSink](#kairossink)
+        * [OtelSink](#otelsink)
+        * [TimescaleDBSink](#timescaledbsink)
     + [Collectors](#collectors)
       - [BagCollector](#bagcollector)
       - [Chained Collectors](#chained-collectors)
@@ -574,7 +584,11 @@ under sources from the metric up towards the root.  The first `_sink` property
 found is used.  Different metrics can be sent to different sinks.  The `_sink` 
 property can be a string or a list so you can send a metric to multiple sinks.
 
-#### Slf4JMetricSink
+#### Internal
+Internal sinks are simple and built in as part of the metrics4j library.
+
+
+##### Slf4JMetricSink
 Reports metrics to an Slf4j logger.  The log-level attribute controls the log level (DEBUG, WARN, INFO, etc).
 ```hocon
 sinks: {
@@ -587,7 +601,7 @@ sinks: {
 
 * _log-level:_ (INFO, DEBUG, WARN, ERROR, TRACE), log level to use when reporting metrics
 
-#### TelnetSink
+##### TelnetSink
 
 Sends data using the telnet protocol supported by OpenTSDB and KairosDB.
 
@@ -613,7 +627,7 @@ respectively
 if set to MILLISECONDS the sink will use the 'putm' command
 
 
-#### GraphitePlaintextSink
+##### GraphitePlaintextSink
 
 Sends data using the plaintext protocol.  It takes three attributes for host, port
 and whether to include tags.
@@ -635,55 +649,78 @@ sinks: {
 * _protocol:_ (UDP/**TCP**) Protocol to use
 * _max-udp-packet-size:_ (**1024**) Max packet size when using UDP
 
-#### InfluxSink
+##### StatsDTCPSink
+
+Sends metrics to a StatsD instance.  You can also set the source property _statsd_type_ to specify
+the type of metric, it defaults to 'g'
+
+* _host:_ Host to connect to
+* _port:_ Port to use
+* _protocol:_ (UDP/**TCP**) Protocol to use
+* _max-udp-packet-size:_ (**1024**) Max packet size when using UDP
+
+#### External
+External sinks are provided as plugins that have their own dependencies.  These
+are packaged and deployed separatedly from metrics4j.
+
+To use an external sink you specify __folder_ parameter as well as the __class_ parameter. 
+The folder path is the location of the sink jar and all of its dependencies.  A spearate
+class loader is used for the sink so the dependencies will not interfere with the application.
 
-The Influx sink is a separate jar that needs to be placed in the classpath along 
-with its dependencies (it includes the apache httpclient).
+##### InfluxSink
+
+External sink for sending data to InfluxDB.  Because both version 1 and 2 support the same 
+line protocol you can switch between them by changing the host-url metrics are sent to.
 
 ```hocon
 sinks: {
   influx: {
     _class: "org.kairosdb.metrics4jplugin.influxdb.InfluxSink"
+    _folder: "/path/to/sink/folder"
     host-url: "http://localhost:8086/write?db=mydb"
   }
 }
 ```
 
 * _host-url:_ url endpoint for influx
 
-#### PrometheusSink
+##### PrometheusSink
 
-The Prometheus sink is a separate jar that needs to be placed in the classpath along
-with its dependencies (it includes the prometheus simpleclient and simpleclient_httpserver).
+External sink that opens a port for a prometheus server to scrape the metrics from.
 
 Prometheus requires both a sink and a trigger to be defined.  They both need to be referenced
 in the sources section as well.
 
+The trigger is effectively when the server scrapes the endpoint.
+
 ```hocon
 sinks: {
   prometheus: {
     _class: "org.kairosdb.metrics4jplugin.prometheus.PrometheusSink"
+    _folder: "/path/to/sink/folder"
     listen-port: 9090
   }
 }
 
 triggers: {
   prometheus: {
     _class: "org.kairosdb.metrics4jplugin.prometheus.PrometheusTrigger"
+    _folder: "/path/to/sink/folder"
   }
 }
 ```
 
 * _listen-port:_ Port on which to listen for prometheus scrap requests
 
-#### KairosSink
+##### KairosSink
 
-The Kairos sink is a separate jar that needs to be placed in the classpath along
-with its dependencies.
+External sink for sending data to KairosDB.  Metrics can be sent either via http or telnet
+by specifying the appropriate configurations.
 
 ```hocon
 kairos: {
   _class: "org.kairosdb.metrics4jplugin.kairosdb.KairosSink"
+  _folder: "/path/to/sink/folder"
   host-url: "http://192.168.1.55:8080"
   #telnet-host: "192.168.1.55"
   #telnet-port: 4242
@@ -698,19 +735,29 @@ the kairosdb client.
 * _telnet-port:_ (**4242**) Telnet port
 * _ttl:_ (**0s**) Optional ttl.  Can be specified like so "60s" or "24h", this can also be set as a prop in the source for specific metrics  
 
-#### TimescaleDBSink
+##### OtelSink
 
-TODO: https://docs.timescale.com/latest/using-timescaledb/writing-data
+External Open Telemetry sink for sending metrics via OTLP using grpc protocol.
 
-#### StatsDTCPSink
+```hocon
+sinks: {
+  influx: {
+    _class: "org.kairosdb.metrics4jplugin.opentelemetry.OtelSink"
+    _folder: "/path/to/sink/folder"
+    endpoint: "http://localhost:4317"
+    name: "metrics4j"
+  }
+}
+```
+
+* _endpoint:_ (**http://localhost:4317**) Url for the grpc endpoint of the otlp collector.
+* _name:_ (**metrics4j**) Service name passed as part of the instrumentation scope info.
+
+##### TimescaleDBSink
+
+TODO: https://docs.timescale.com/latest/using-timescaledb/writing-data
 
-Sends metrics to a StatsD instance.  You can also set the source property _statsd_type_ to specify
-the type of metric, it defaults to 'g'
 
-* _host:_ Host to connect to
-* _port:_ Port to use
-* _protocol:_ (UDP/**TCP**) Protocol to use
-* _max-udp-packet-size:_ (**1024**) Max packet size when using UDP
 
 ### Collectors
 A collector defines how to collect values from a source.  For reportSize() you could
@@ -951,6 +998,7 @@ metrics4j: {
         sausage: "double"
       }
       class-name-attributes: ["type", "name"]
+      default-metric-type: "counter"
     }
   }
   _dump-file: "/home/bhawkins/programs/kafka_2.13-2.5.1/dump.conf"
@@ -962,8 +1010,9 @@ metrics4j: {
 also supports CompositeData but this is a special case.
 * _class-name-attributes:_ A list of JMX attributes used to create the class name and how each JMX source shows up in the configuration file.
 Attributes not specified as part of the class name will show up as tags on the reported metric.
+* _default-metric-type:_ (**counter**) Set to either 'counter' or 'gauge'.  This tags metrics so downstream metric databases will know how to deal with numeric values.  Very important when using the open telemetry plugin.  You can override this value in the source with the _metric_type_ property, example below.
 
-The type can be overridden at the source level by adding the _jmx_type_ property.  For example
+The jmx type can be overridden at the source level by adding the _jmx_type_ property.  For example
 when reporting JMX metrics from Kakfa they declar the type to be `java.lang.Object`.  Most
 of the time that is a long value but in some cases it is an int, so for those, an exception
 is added directly to that source like in the example below.
@@ -975,6 +1024,7 @@ metrics4j: {
         UnderReplicatedPartitions.Value: {
           _prop: {
             jmx_type: "int"
+            metric_type: "gauge"
           }
         }
       }

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

@@ -332,6 +332,10 @@ public static void addSource(String className, String methodName, Map<String, St
 		This method is provided for unit test purposes.  It lets you define
 		a collectors object for a specific metric call.  See the unit tests
 		in MetricSourceManagerTest to see how to use this method.
+		@param <T> Returned collector as defined by reporterClass
+		@param stats Metric collector that will be used in the code.  For unit testing this will likely be a mock
+		@param reporterClass  Reporter class
+		@return Proxy instance of reprter class
 	*/
 	public static <T> T setCollectorForSource(MetricCollector stats, Class<T> reporterClass)
 	{

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

@@ -41,7 +41,7 @@ private MetricThreadHelper()
 	/**
 	 Sets the time which metrics will be reported with.  This only has effect on
 	 non aggregated collectors like the BagCollector.
-	 @param time
+	 @param time Timestamp to report the metric
 	 */
 	public static void setReportTime(Instant time)
 	{
@@ -60,7 +60,7 @@ public static void clearReportTime()
 
 	/**
 	 Returns the set report time or Instance.MIN if not set.
-	 @return
+	 @return Report time for metric
 	 */
 	public static Instant getReportTime()
 	{
@@ -69,8 +69,8 @@ public static Instant getReportTime()
 
 	/**
 	 Adds a tag to all metrics that will be reported from the current thread.
-	 @param name
-	 @param value
+	 @param name Name of tag
+	 @param value Value of tag
 	 */
 	public static void addTag(String name, String value)
 	{
@@ -79,8 +79,8 @@ public static void addTag(String name, String value)
 
 	/**
 	 Returns a value of a tag if set on the thread, null otherwise.
-	 * @param name
-	 * @return
+	 * @param name Name of tag
+	 * @return Value of tag
 	 */
 	public static String getTag(String name)
 	{
@@ -89,7 +89,7 @@ public static String getTag(String name)
 
 	/**
 	 Removes a single tag from the thread.
-	 @param name
+	 @param name Name of tag
 	 */
 	public static void removeTag(String name)
 	{
@@ -108,7 +108,7 @@ public static void clearTags()
 
 	/**
 	 Iterator of all tags set on the thread.
-	 @return
+	 @return Iterator of all tag keys and values
 	 */
 	public static Iterator<Map.Entry<String, String>> getTagIterator()
 	{

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

@@ -12,7 +12,7 @@ public interface Collector extends PostConstruct, MetricCollector
 	 The first instance of a collector is unmarshalled from configuration using
 	 hocon, all other instances are cloned from that first one so the clone
 	 method should pass along any configuration that was set.
-	 @return
+	 @return Clone of this collector
 	 */
 	Collector clone();
 }

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

@@ -17,7 +17,7 @@
 
 /**
  ChainedCollector lets you report metrics to more than one collector.
- @param <C>
+ @param <C> Type of collector to chain
  */
 @ToString
 @EqualsAndHashCode

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

@@ -18,15 +18,15 @@ public interface ThreadReporter
 {
 	/**
 	 Set the time for data points to be reported
-	 @param time
+	 @param time Timestamp to use when reporting metrics
 	 */
 	void setReportTime(long time);
 
 	/**
 	 This lets you put a tag to all data points submitted to sub interfaces of
 	 ThreadReporter
-	 @param name
-	 @param value
+	 @param name Name of tag to add to thread
+	 @param value Value of tag to add to thread
 	 */
 	void addTag(String name, String value);
 	void removeTag(String name);

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

@@ -1,24 +1,17 @@
 package org.kairosdb.metrics4j.collectors.helpers;
 
-import lombok.Setter;
 import org.kairosdb.metrics4j.collectors.Collector;
 import org.kairosdb.metrics4j.collectors.DurationCollector;
 import org.kairosdb.metrics4j.internal.DoubleTimeReporter;
 import org.kairosdb.metrics4j.internal.LongTimeReporter;
 import org.kairosdb.metrics4j.internal.TimeReporter;
 
-import java.time.Duration;
 import java.time.temporal.ChronoUnit;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.concurrent.Callable;
 
-import static org.kairosdb.metrics4j.internal.ReportingContext.AGGREGATION_DELTA_VALUE;
-import static org.kairosdb.metrics4j.internal.ReportingContext.AGGREGATION_KEY;
 import static org.kairosdb.metrics4j.internal.ReportingContext.CHRONO_UNIT_KEY;
-import static org.kairosdb.metrics4j.internal.ReportingContext.TYPE_COUNTER_VALUE;
-import static org.kairosdb.metrics4j.internal.ReportingContext.TYPE_GAUGE_VALUE;
-import static org.kairosdb.metrics4j.internal.ReportingContext.TYPE_KEY;
 
 
 public abstract class TimerCollector implements DurationCollector
@@ -54,6 +47,7 @@ public TimerCollector()
 
 	/**
 	 Unit to report metric as.  Supported units are NANOS, MICROS, MILLIS, SECONDS, MINUTES, HOURS, DAYS
+	 @param reportUnit Time unit
 	 */
 	public void setReportUnit(ChronoUnit reportUnit)
 	{
@@ -69,7 +63,7 @@ public ChronoUnit getReportUnit()
 
 	/**
 	 Report format is either LONG or DOUBLE.  Double truncates at 3 decimal places
-	 * @param reportFormat
+	 * @param reportFormat Report format
 	 */
 	public void setReportFormat(ReportFormat reportFormat)
 	{

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

@@ -77,7 +77,7 @@ private void clear()
 
 	/**
 	 Not thread safe
-	 @return
+	 @return Call count
 	 */
 	public long getCount()
 	{