feat: add the UpDownCounter instrument (#1120)

packages/opentelemetry-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.

packages/opentelemetry-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.

packages/opentelemetry-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.

packages/opentelemetry-exporter-prometheus/src/prometheus.ts

@@ -191,10 +191,9 @@ export class PrometheusExporter implements MetricExporter {
 
  switch (record.descriptor.metricKind) {
  case MetricKind.COUNTER:
- // there is no such thing as a non-monotonic counter in prometheus
- return record.descriptor.monotonic
- ? new Counter(metricObject)
- : new Gauge(metricObject);
+ return new Counter(metricObject);
+ case MetricKind.UP_DOWN_COUNTER:
+ return new Gauge(metricObject);
  case MetricKind.OBSERVER:
  return new Gauge(metricObject);
  default:

packages/opentelemetry-exporter-prometheus/test/prometheus.test.ts

@@ -384,10 +384,9 @@ describe('PrometheusExporter', () => {
  });
  });
 
- it('should export a non-monotonic counter as a gauge', done => {
- const counter = meter.createCounter('counter', {
+ it('should export a UpDownCounter as a gauge', done => {
+ const counter = meter.createUpDownCounter('counter', {
  description: 'a test description',
- monotonic: false,
  });
 
  counter.bind({ key1: 'labelValue1' }).add(20);

packages/opentelemetry-metrics/src/BoundInstrument.ts

@@ -24,19 +24,16 @@ import { Aggregator } from './export/types';
 export class BaseBoundInstrument {
  protected _labels: api.Labels;
  protected _logger: api.Logger;
- protected _monotonic: boolean;
 
  constructor(
  labels: api.Labels,
  logger: api.Logger,
- monotonic: boolean,
  private readonly _disabled: boolean,
  private readonly _valueType: api.ValueType,
  private readonly _aggregator: Aggregator
  ) {
  this._labels = labels;
  this._logger = logger;
- this._monotonic = monotonic;
  }
 
  update(value: number): void {
@@ -72,18 +69,17 @@ export class BoundCounter extends BaseBoundInstrument
  constructor(
  labels: api.Labels,
  disabled: boolean,
- monotonic: boolean,
  valueType: api.ValueType,
  logger: api.Logger,
  aggregator: Aggregator
  ) {
- super(labels, logger, monotonic, disabled, valueType, aggregator);
+ super(labels, logger, disabled, valueType, aggregator);
  }
 
  add(value: number): void {
- if (this._monotonic && value < 0) {
+ if (value < 0) {
  this._logger.error(
- `Monotonic counter cannot descend for ${Object.values(this._labels)}`
+ `Counter cannot descend for ${Object.values(this._labels)}`
  );
  return;
  }
@@ -93,7 +89,29 @@ export class BoundCounter extends BaseBoundInstrument
 }
 
 /**
- * BoundValueRecorder is an implementation of the {@link BoundValueRecorder} interface.
+ * BoundUpDownCounter allows the SDK to observe/record a single metric event.
+ * The value of single instrument in the `UpDownCounter` associated with
+ * specified Labels.
+ */
+export class BoundUpDownCounter extends BaseBoundInstrument
+ implements api.BoundCounter {
+ constructor(
+ labels: api.Labels,
+ disabled: boolean,
+ valueType: api.ValueType,
+ logger: api.Logger,
+ aggregator: Aggregator
+ ) {
+ super(labels, logger, disabled, valueType, aggregator);
+ }
+
+ add(value: number): void {
+ this.update(value);
+ }
+}
+
+/**
+ * BoundMeasure is an implementation of the {@link BoundMeasure} interface.
  */
 export class BoundValueRecorder extends BaseBoundInstrument
  implements api.BoundValueRecorder {
@@ -102,13 +120,12 @@ export class BoundValueRecorder extends BaseBoundInstrument
  constructor(
  labels: api.Labels,
  disabled: boolean,
- monotonic: boolean,
  absolute: boolean,
  valueType: api.ValueType,
  logger: api.Logger,
  aggregator: Aggregator
  ) {
- super(labels, logger, monotonic, disabled, valueType, aggregator);
+ super(labels, logger, disabled, valueType, aggregator);
  this._absolute = absolute;
  }
 
@@ -137,11 +154,10 @@ export class BoundObserver extends BaseBoundInstrument {
  constructor(
  labels: api.Labels,
  disabled: boolean,
- monotonic: boolean,
  valueType: api.ValueType,
  logger: api.Logger,
  aggregator: Aggregator
  ) {
- super(labels, logger, monotonic, disabled, valueType, aggregator);
+ super(labels, logger, disabled, valueType, aggregator);
  }
 }

packages/opentelemetry-metrics/src/Meter.ts

@@ -18,6 +18,7 @@ import * as api from '@opentelemetry/api';
 import { ConsoleLogger } from '@opentelemetry/core';
 import { Resource } from '@opentelemetry/resources';
 import { BaseBoundInstrument } from './BoundInstrument';
+import { UpDownCounterMetric } from './UpDownCounterMetric';
 import {
  Metric,
  CounterMetric,
@@ -72,10 +73,9 @@ export class Meter implements api.Meter {
  return api.NOOP_VALUE_RECORDER_METRIC;
  }
  const opt: MetricOptions = {
- absolute: true, // value recorders are defined as absolute by default
- monotonic: false, // not applicable to value recorder, set to false
  logger: this._logger,
  ...DEFAULT_METRIC_OPTIONS,
+ absolute: true, // value recorders are defined as absolute by default
  ...options,
  };
 
@@ -104,8 +104,6 @@ export class Meter implements api.Meter {
  return api.NOOP_COUNTER_METRIC;
  }
  const opt: MetricOptions = {
- monotonic: true, // Counters are defined as monotonic by default
- absolute: false, // not applicable to counter, set to false
  logger: this._logger,
  ...DEFAULT_METRIC_OPTIONS,
  ...options,
@@ -115,6 +113,41 @@ export class Meter implements api.Meter {
  return 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.
+ *
+ * @param name the name of the metric.
+ * @param [options] the metric options.
+ */
+ createUpDownCounter(
+ name: string,
+ options?: api.MetricOptions
+ ): api.UpDownCounter {
+ if (!this._isValidName(name)) {
+ this._logger.warn(
+ `Invalid metric name ${name}. Defaulting to noop metric implementation.`
+ );
+ return api.NOOP_COUNTER_METRIC;
+ }
+ const opt: MetricOptions = {
+ logger: this._logger,
+ ...DEFAULT_METRIC_OPTIONS,
+ ...options,
+ };
+ const upDownCounter = new UpDownCounterMetric(
+ name,
+ opt,
+ this._batcher,
+ this._resource
+ );
+ this._registerMetric(name, upDownCounter);
+ return upDownCounter;
+ }
+
  /**
  * Creates a new observer metric.
  * @param name the name of the metric.
@@ -128,8 +161,6 @@ export class Meter implements api.Meter {
  return api.NOOP_OBSERVER_METRIC;
  }
  const opt: MetricOptions = {
- monotonic: false, // Observers are defined as non-monotonic by default
- absolute: false, // not applicable to observer, set to false
  logger: this._logger,
  ...DEFAULT_METRIC_OPTIONS,
  ...options,
@@ -188,7 +219,8 @@ export class Meter implements api.Meter {
  *
  * 2. The first character must be non-numeric, non-space, non-punctuation
  *
- * 3. Subsequent characters must be belong to the alphanumeric characters, '_', '.', and '-'.
+ * 3. Subsequent characters must be belong to the alphanumeric characters,
+ * '_', '.', and '-'.
  *
  * Names are case insensitive
  *

packages/opentelemetry-metrics/src/Metric.ts

@@ -31,7 +31,6 @@ import { hashLabels } from './Utils';
 /** This is a SDK implementation of {@link Metric} interface. */
 export abstract class Metric<T extends BaseBoundInstrument>
  implements api.UnboundMetric<T> {
- protected readonly _monotonic: boolean;
  protected readonly _disabled: boolean;
  protected readonly _valueType: api.ValueType;
  protected readonly _logger: api.Logger;
@@ -44,7 +43,6 @@ export abstract class Metric<T extends BaseBoundInstrument>
  private readonly _kind: MetricKind,
  readonly resource: Resource
  ) {
- this._monotonic = _options.monotonic;
  this._disabled = _options.disabled;
  this._valueType = _options.valueType;
  this._logger = _options.logger;
@@ -98,7 +96,6 @@ export abstract class Metric<T extends BaseBoundInstrument>
  unit: this._options.unit,
  metricKind: this._kind,
  valueType: this._valueType,
- monotonic: this._monotonic,
  };
  }
 
@@ -119,7 +116,6 @@ export class CounterMetric extends Metric<BoundCounter> implements api.Counter {
  return new BoundCounter(
  labels,
  this._disabled,
- this._monotonic,
  this._valueType,
  this._logger,
  // @todo: consider to set to CounterSumAggregator always.
@@ -130,8 +126,8 @@ export class CounterMetric extends Metric<BoundCounter> implements api.Counter {
  /**
  * Adds the given value to the current value. Values cannot be negative.
  * @param value the value to add.
- * @param [labels = {}] key-values pairs that are associated with a specific metric
- * that you want to record.
+ * @param [labels = {}] key-values pairs that are associated with a specific
+ * metric that you want to record.
  */
  add(value: number, labels: api.Labels = {}) {
  this.bind(labels).add(value);
@@ -156,7 +152,6 @@ export class ValueRecorderMetric extends Metric<BoundValueRecorder>
  return new BoundValueRecorder(
  labels,
  this._disabled,
- this._monotonic,
  this._absolute,
  this._valueType,
  this._logger,
@@ -187,7 +182,6 @@ export class ObserverMetric extends Metric<BoundObserver>
  return new BoundObserver(
  labels,
  this._disabled,
- this._monotonic,
  this._valueType,
  this._logger,
  this._batcher.aggregatorFor(this._descriptor)