feat(instrumentation): added synchronous gauge

Author: clintonb

api/src/index.ts

@@ -43,6 +43,7 @@ export { MeterProvider } from './metrics/MeterProvider';
 export {
   ValueType,
   Counter,
+  Gauge,
   Histogram,
   MetricOptions,
   Observable,

api/src/metrics/Meter.ts

@@ -17,6 +17,7 @@
 import {
   BatchObservableCallback,
   Counter,
+  Gauge,
   Histogram,
   MetricAttributes,
   MetricOptions,
@@ -45,6 +46,16 @@ export interface MeterOptions {
  * for the exported metric are deferred.
  */
 export interface Meter {
+  /**
+   * Creates and returns a new `Gauge`.
+   * @param name the name of the metric.
+   * @param [options] the metric options.
+   */
+  createGauge<AttributesTypes extends MetricAttributes = MetricAttributes>(
+    name: string,
+    options?: MetricOptions
+  ): Gauge<AttributesTypes>;
+
   /**
    * Creates and returns a new `Histogram`.
    * @param name the name of the metric.

api/src/metrics/Metric.ts

@@ -98,6 +98,15 @@ export interface UpDownCounter<
   add(value: number, attributes?: AttributesTypes, context?: Context): void;
 }
 
+export interface Gauge<
+  AttributesTypes extends MetricAttributes = MetricAttributes,
+> {
+  /**
+   * Records a measurement. Value of the measurement must not be negative.
+   */
+  record(value: number, attributes?: AttributesTypes, context?: Context): void;
+}
+
 export interface Histogram<
   AttributesTypes extends MetricAttributes = MetricAttributes,
 > {

api/src/metrics/NoopMeter.ts

@@ -18,15 +18,16 @@ import { Meter } from './Meter';
 import {
   BatchObservableCallback,
   Counter,
+  Gauge,
   Histogram,
+  MetricAttributes,
   MetricOptions,
+  Observable,
   ObservableCallback,
   ObservableCounter,
   ObservableGauge,
   ObservableUpDownCounter,
   UpDownCounter,
-  MetricAttributes,
-  Observable,
 } from './Metric';
 
 /**
@@ -36,6 +37,13 @@ import {
 export class NoopMeter implements Meter {
   constructor() {}
 
+  /**
+   * @see {@link Meter.createGauge}
+   */
+  createGauge(_name: string, _options?: MetricOptions): Histogram {
+    return NOOP_GAUGE_METRIC;
+  }
+
   /**
    * @see {@link Meter.createHistogram}
    */
@@ -114,6 +122,10 @@ export class NoopUpDownCounterMetric
   add(_value: number, _attributes: MetricAttributes): void {}
 }
 
+export class NoopGaugeMetric extends NoopMetric implements Gauge {
+  record(_value: number, _attributes: MetricAttributes): void {}
+}
+
 export class NoopHistogramMetric extends NoopMetric implements Histogram {
   record(_value: number, _attributes: MetricAttributes): void {}
 }
@@ -140,6 +152,7 @@ export const NOOP_METER = new NoopMeter();
 
 // Synchronous instruments
 export const NOOP_COUNTER_METRIC = new NoopCounterMetric();
+export const NOOP_GAUGE_METRIC = new NoopGaugeMetric();
 export const NOOP_HISTOGRAM_METRIC = new NoopHistogramMetric();
 export const NOOP_UP_DOWN_COUNTER_METRIC = new NoopUpDownCounterMetric();
 

api/test/common/noop-implementations/noop-meter.test.ts

@@ -24,6 +24,7 @@ import {
   NOOP_OBSERVABLE_UP_DOWN_COUNTER_METRIC,
   NOOP_UP_DOWN_COUNTER_METRIC,
   createNoopMeter,
+  NOOP_GAUGE_METRIC,
 } from '../../../src/metrics/NoopMeter';
 import { NoopMeterProvider } from '../../../src/metrics/NoopMeterProvider';
 
@@ -116,6 +117,17 @@ describe('NoopMeter', () => {
     );
   });
 
+  it('gauge should not crash', () => {
+    const meter = new NoopMeterProvider().getMeter('test-noop');
+    const observableGauge = meter.createGauge('some-name');
+
+    // ensure the correct noop const is returned
+    assert.strictEqual(observableGauge, NOOP_GAUGE_METRIC);
+
+    const gaugeWithOptions = meter.createGauge('some-name', options);
+    assert.strictEqual(gaugeWithOptions, NOOP_GAUGE_METRIC);
+  });
+
   it('observable up down counter should not crash', () => {
     const meter = new NoopMeterProvider().getMeter('test-noop');
     const observableUpDownCounter =

experimental/packages/opentelemetry-exporter-metrics-otlp-http/src/OTLPMetricExporterBase.ts

@@ -41,6 +41,7 @@ export const DeltaTemporalitySelector: AggregationTemporalitySelector = (
   switch (instrumentType) {
     case InstrumentType.COUNTER:
     case InstrumentType.OBSERVABLE_COUNTER:
+    case InstrumentType.GAUGE:
     case InstrumentType.HISTOGRAM:
     case InstrumentType.OBSERVABLE_GAUGE:
       return AggregationTemporality.DELTA;
@@ -57,6 +58,7 @@ export const LowMemoryTemporalitySelector: AggregationTemporalitySelector = (
     case InstrumentType.COUNTER:
     case InstrumentType.HISTOGRAM:
       return AggregationTemporality.DELTA;
+    case InstrumentType.GAUGE:
     case InstrumentType.UP_DOWN_COUNTER:
     case InstrumentType.OBSERVABLE_UP_DOWN_COUNTER:
     case InstrumentType.OBSERVABLE_COUNTER:

packages/sdk-metrics/src/InstrumentDescriptor.ts

@@ -23,6 +23,7 @@ import { equalsCaseInsensitive } from './utils';
  */
 export enum InstrumentType {
   COUNTER = 'COUNTER',
+  GAUGE = 'GAUGE',
   HISTOGRAM = 'HISTOGRAM',
   UP_DOWN_COUNTER = 'UP_DOWN_COUNTER',
   OBSERVABLE_COUNTER = 'OBSERVABLE_COUNTER',

packages/sdk-metrics/src/Instruments.ts

@@ -22,6 +22,7 @@ import {
   ValueType,
   UpDownCounter,
   Counter,
+  Gauge,
   Histogram,
   Observable,
   ObservableCallback,
@@ -110,6 +111,18 @@ export class CounterInstrument extends SyncInstrument implements Counter {
   }
 }
 
+/**
+ * The class implements {@link Gauge} interface.
+ */
+export class GaugeInstrument extends SyncInstrument implements Gauge {
+  /**
+   * Records a measurement.
+   */
+  record(value: number, attributes?: MetricAttributes, ctx?: Context): void {
+    this._record(value, attributes, ctx);
+  }
+}
+
 /**
  * The class implements {@link Histogram} interface.
  */

packages/sdk-metrics/src/Meter.ts

@@ -25,13 +25,16 @@ import {
   ObservableUpDownCounter,
   BatchObservableCallback,
   Observable,
+  Attributes,
+  Gauge,
 } from '@opentelemetry/api';
 import {
   createInstrumentDescriptor,
   InstrumentType,
 } from './InstrumentDescriptor';
 import {
   CounterInstrument,
+  GaugeInstrument,
   HistogramInstrument,
   ObservableCounterInstrument,
   ObservableGaugeInstrument,
@@ -46,6 +49,22 @@ import { MeterSharedState } from './state/MeterSharedState';
 export class Meter implements IMeter {
   constructor(private _meterSharedState: MeterSharedState) {}
 
+  /**
+   * Create a {@link Gauge} instrument.
+   */
+  createGauge<AttributesTypes extends Attributes = Attributes>(
+    name: string,
+    options?: MetricOptions
+  ): Gauge<AttributesTypes> {
+    const descriptor = createInstrumentDescriptor(
+      name,
+      InstrumentType.GAUGE,
+      options
+    );
+    const storage = this._meterSharedState.registerMetricStorage(descriptor);
+    return new GaugeInstrument(storage, descriptor);
+  }
+
   /**
    * Create a {@link Histogram} instrument.
    */

packages/sdk-metrics/src/aggregator/ExponentialHistogram.ts

@@ -580,6 +580,7 @@ export class ExponentialHistogramAggregator
 
         // determine if instrument allows negative values.
         const allowsNegativeValues =
+          descriptor.type === InstrumentType.GAUGE ||
           descriptor.type === InstrumentType.UP_DOWN_COUNTER ||
           descriptor.type === InstrumentType.OBSERVABLE_GAUGE ||
           descriptor.type === InstrumentType.OBSERVABLE_UP_DOWN_COUNTER;

packages/sdk-metrics/src/aggregator/Histogram.ts

@@ -231,6 +231,7 @@ export class HistogramAggregator implements Aggregator<HistogramAccumulation> {
 
         // determine if instrument allows negative values.
         const allowsNegativeValues =
+          descriptor.type === InstrumentType.GAUGE ||
           descriptor.type === InstrumentType.UP_DOWN_COUNTER ||
           descriptor.type === InstrumentType.OBSERVABLE_GAUGE ||
           descriptor.type === InstrumentType.OBSERVABLE_UP_DOWN_COUNTER;

packages/sdk-metrics/src/view/Aggregation.ts

@@ -182,6 +182,7 @@ export class DefaultAggregation extends Aggregation {
       case InstrumentType.OBSERVABLE_UP_DOWN_COUNTER: {
         return SUM_AGGREGATION;
       }
+      case InstrumentType.GAUGE:
       case InstrumentType.OBSERVABLE_GAUGE: {
         return LAST_VALUE_AGGREGATION;
       }

packages/sdk-metrics/test/export/ConsoleMetricExporter.test.ts

@@ -160,6 +160,7 @@ describe('ConsoleMetricExporter', () => {
         switch (instrumentType) {
           case InstrumentType.COUNTER:
           case InstrumentType.OBSERVABLE_COUNTER:
+          case InstrumentType.GAUGE:
           case InstrumentType.HISTOGRAM:
           case InstrumentType.OBSERVABLE_GAUGE:
             return AggregationTemporality.DELTA;

packages/sdk-metrics/test/export/utils.ts

@@ -29,6 +29,7 @@ const instrumentTypes = [
   InstrumentType.UP_DOWN_COUNTER,
   InstrumentType.OBSERVABLE_UP_DOWN_COUNTER,
   InstrumentType.HISTOGRAM,
+  InstrumentType.GAUGE,
   InstrumentType.OBSERVABLE_GAUGE,
 ];