Add non bound usage to the various metric instruments API (#715)

* WIP on non-bound instrument usages

* Add API methods for non-bound-instrument usages

* add missing javadoc

* add some additional javadoc

api/src/main/java/io/opentelemetry/metrics/DefaultMeter.java

@@ -175,6 +175,9 @@ public final class DefaultMeter implements Meter {
     /** Creates a new {@code NoopBound}. */
     private NoopLongGauge() {}
 
+    @Override
+    public void set(long val, LabelSet labelSet) {}
+
     @Override
     public NoopBoundLongGauge bind(LabelSet labelSet) {
       Utils.checkNotNull(labelSet, "labelSet");
@@ -215,6 +218,9 @@ public final class DefaultMeter implements Meter {
     /** Creates a new {@code NoopBound}. */
     private NoopDoubleGauge() {}
 
+    @Override
+    public void set(double val, LabelSet labelSet) {}
+
     @Override
     public NoopBoundDoubleGauge bind(LabelSet labelSet) {
       Utils.checkNotNull(labelSet, "labelSet");
@@ -255,6 +261,9 @@ public final class DefaultMeter implements Meter {
     /** Creates a new {@code NoopBound}. */
     private NoopDoubleCounter() {}
 
+    @Override
+    public void add(double delta, LabelSet labelSet) {}
+
     @Override
     public NoopBoundDoubleCounter bind(LabelSet labelSet) {
       Utils.checkNotNull(labelSet, "labelSet");
@@ -295,6 +304,9 @@ public final class DefaultMeter implements Meter {
     /** Creates a new {@code NoopBound}. */
     private NoopLongCounter() {}
 
+    @Override
+    public void add(long delta, LabelSet labelSet) {}
+
     @Override
     public NoopBoundLongCounter bind(LabelSet labelSet) {
       Utils.checkNotNull(labelSet, "labelSet");
@@ -334,6 +346,11 @@ public final class DefaultMeter implements Meter {
     /** Creates a new {@code NoopDoubleMeasure}. */
     private NoopDoubleMeasure() {}
 
+    @Override
+    public void record(double value, LabelSet labelSet) {
+      Utils.checkArgument(value >= 0.0, "Unsupported negative values.");
+    }
+
     @Override
     public NoopBoundDoubleMeasure bind(LabelSet labelSet) {
       Utils.checkNotNull(labelSet, "labelSet");
@@ -374,6 +391,11 @@ public final class DefaultMeter implements Meter {
   private static final class NoopLongMeasure implements LongMeasure {
     private NoopLongMeasure() {}
 
+    @Override
+    public void record(long value, LabelSet labelSet) {
+      Utils.checkArgument(value >= 0, "Unsupported negative values.");
+    }
+
     @Override
     public NoopBoundLongMeasure bind(LabelSet labelSet) {
       Utils.checkNotNull(labelSet, "labelSet");

api/src/main/java/io/opentelemetry/metrics/DoubleCounter.java

@@ -52,6 +52,18 @@ import javax.annotation.concurrent.ThreadSafe;
 @ThreadSafe
 public interface DoubleCounter extends Counter<BoundDoubleCounter> {
 
+  /**
+   * Adds the given {@code delta} to the current value. The values can be negative iff monotonic was
+   * set to {@code false}.
+   *
+   * <p>The value added is associated with the current {@code Context} and provided LabelSet.
+   *
+   * @param delta the value to add.
+   * @param labelSet the labels to be associated to this recording
+   * @since 0.1.0
+   */
+  void add(double delta, LabelSet labelSet);
+
   @Override
   BoundDoubleCounter bind(LabelSet labelSet);
 

api/src/main/java/io/opentelemetry/metrics/DoubleGauge.java

@@ -36,7 +36,7 @@ import javax.annotation.concurrent.ThreadSafe;
  *           .setUnit("1")
  *           .setLabelKeys(Collections.singletonList("Key"))
  *           .build();
- *   // It is recommended to keep a reference to a Bound Instrument.
+ *   // It is recommended to keep a reference to a Bound Metric.
  *   private static final BoundDoubleGauge someWorkBound =
  *       gauge.getBound(Collections.singletonList("SomeWork"));
  *
@@ -52,6 +52,18 @@ import javax.annotation.concurrent.ThreadSafe;
  */
 @ThreadSafe
 public interface DoubleGauge extends Gauge<BoundDoubleGauge> {
+
+  /**
+   * Sets the given value.
+   *
+   * <p>The value added is associated with the current {@code Context} and provided LabelSet.
+   *
+   * @param val the new value.
+   * @param labelSet the labels to be associated to this recording
+   * @since 0.1.0
+   */
+  void set(double val, LabelSet labelSet);
+
   @Override
   BoundDoubleGauge bind(LabelSet labelSet);
 

api/src/main/java/io/opentelemetry/metrics/DoubleMeasure.java

@@ -48,6 +48,18 @@ import javax.annotation.concurrent.ThreadSafe;
  */
 @ThreadSafe
 public interface DoubleMeasure extends Measure<BoundDoubleMeasure> {
+
+  /**
+   * Records the given measurement, associated with the current {@code Context} and provided
+   * LabelSet.
+   *
+   * @param value the measurement to record.
+   * @param labelSet the labels to be associated to this recording
+   * @throws IllegalArgumentException if value is negative.
+   * @since 0.1.0
+   */
+  void record(double value, LabelSet labelSet);
+
   @Override
   BoundDoubleMeasure bind(LabelSet labelSet);
 

api/src/main/java/io/opentelemetry/metrics/LongCounter.java

@@ -52,6 +52,18 @@ import javax.annotation.concurrent.ThreadSafe;
 @ThreadSafe
 public interface LongCounter extends Metric<BoundLongCounter> {
 
+  /**
+   * Adds the given {@code delta} to the current value. The values can be negative iff monotonic was
+   * set to {@code false}.
+   *
+   * <p>The value added is associated with the current {@code Context} and provided LabelSet.
+   *
+   * @param delta the value to add.
+   * @param labelSet the labels to be associated to this recording.
+   * @since 0.1.0
+   */
+  void add(long delta, LabelSet labelSet);
+
   @Override
   BoundLongCounter bind(LabelSet labelSet);
 

api/src/main/java/io/opentelemetry/metrics/LongGauge.java

@@ -36,7 +36,7 @@ import javax.annotation.concurrent.ThreadSafe;
  *           .setUnit("1")
  *           .setLabelKeys(Collections.singletonList("Key"))
  *           .build();
- *   // It is recommended to keep a reference to a Bound Instrument.
+ *   // It is recommended to keep a reference to a Bound Metric.
  *   private static final BoundLongGauge someWorkBound =
  *       gauge.getBound(Collections.singletonList("SomeWork"));
  *
@@ -53,6 +53,17 @@ import javax.annotation.concurrent.ThreadSafe;
 @ThreadSafe
 public interface LongGauge extends Gauge<BoundLongGauge> {
 
+  /**
+   * Sets the given value for the gauge.
+   *
+   * <p>The value added is associated with the current {@code Context} and provided LabelSet.
+   *
+   * @param val the new value.
+   * @param labelSet the labels to be associated to this value
+   * @since 0.1.0
+   */
+  void set(long val, LabelSet labelSet);
+
   @Override
   BoundLongGauge bind(LabelSet labelSet);
 
@@ -67,7 +78,7 @@ public interface LongGauge extends Gauge<BoundLongGauge> {
   interface BoundLongGauge {
 
     /**
-     * Sets the given value.
+     * Sets the given value for the gauge.
      *
      * <p>The value added is associated with the current {@code Context}.
      *

api/src/main/java/io/opentelemetry/metrics/LongMeasure.java

@@ -48,6 +48,18 @@ import javax.annotation.concurrent.ThreadSafe;
  */
 @ThreadSafe
 public interface LongMeasure extends Measure<BoundLongMeasure> {
+
+  /**
+   * Records the given measurement, associated with the current {@code Context} and provided
+   * LabelSet.
+   *
+   * @param value the measurement to record.
+   * @param labelSet the labels to be associated to this recording
+   * @throws IllegalArgumentException if value is negative.
+   * @since 0.1.0
+   */
+  void record(long value, LabelSet labelSet);
+
   @Override
   BoundLongMeasure bind(LabelSet labelSet);