feat: add the UpDownCounter instrument (open-telemetry#1120)

api/src/metrics/Meter.ts

@@ -14,7 +14,13 @@
  * limitations under the License.
  */
 
-import { MetricOptions, Counter, ValueRecorder, Observer } from './Metric';
+import {
+  MetricOptions,
+  Counter,
+  ValueRecorder,
+  Observer,
+  UpDownCounter,
+} from './Metric';
 
 /**
  * An interface to allow the recording metrics.
@@ -40,6 +46,25 @@ export interface Meter {
    */
   createCounter(name: string, options?: MetricOptions): Counter;
 
+  /**
+   * Creates a new `UpDownCounter` metric. UpDownCounter is a synchronous
+   * instrument and very similar to Counter except that Add(increment)
+   * supports negative increments. It is generally useful for capturing changes
+   * in an amount of resources used, or any quantity that rises and falls
+   * during a request.
+   * Example uses for UpDownCounter:
+   * <ol>
+   *   <li> count the number of active requests. </li>
+   *   <li> count memory in use by instrumenting new and delete. </li>
+   *   <li> count queue size by instrumenting enqueue and dequeue. </li>
+   *   <li> count semaphore up and down operations. </li>
+   * </ol>
+   *
+   * @param name the name of the metric.
+   * @param [options] the metric options.
+   */
+  createUpDownCounter(name: string, options?: MetricOptions): UpDownCounter;
+
   /**
    * Creates a new `Observer` metric.
    * @param name the name of the metric.

api/src/metrics/Metric.ts

@@ -48,12 +48,7 @@ export interface MetricOptions {
   disabled?: boolean;
 
   /**
-   * Asserts that this metric may only increase (e.g. time spent).
-   */
-  monotonic?: boolean;
-
-  /**
-   * (ValueRecorder only, default true) Asserts that this metric will only accept
+   * (Measure only, default true) Asserts that this metric will only accept
    * non-negative values (e.g. disk usage).
    */
   absolute?: boolean;
@@ -125,6 +120,13 @@ export interface Counter extends UnboundMetric<BoundCounter> {
   add(value: number, labels?: Labels): void;
 }
 
+export interface UpDownCounter extends UnboundMetric<BoundCounter> {
+  /**
+   * Adds the given value to the current value. Values can be negative.
+   */
+  add(value: number, labels?: Labels): void;
+}
+
 export interface ValueRecorder extends UnboundMetric<BoundValueRecorder> {
   /**
    * Records the given value to this value recorder.

api/src/metrics/NoopMeter.ts

@@ -22,6 +22,7 @@ import {
   Counter,
   ValueRecorder,
   Observer,
+  UpDownCounter,
 } from './Metric';
 import { BoundValueRecorder, BoundCounter } from './BoundInstrument';
 import { CorrelationContext } from '../correlation_context/CorrelationContext';
@@ -53,6 +54,15 @@ export class NoopMeter implements Meter {
     return NOOP_COUNTER_METRIC;
   }
 
+  /**
+   * Returns a constant noop UpDownCounter.
+   * @param name the name of the metric.
+   * @param [options] the metric options.
+   */
+  createUpDownCounter(name: string, options?: MetricOptions): UpDownCounter {
+    return NOOP_COUNTER_METRIC;
+  }
+
   /**
    * Returns constant noop observer.
    * @param name the name of the metric.