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.