feat(sdk-metrics): added synchronous gauge to SDK (#4565)

* feat(instrumentation): added synchronous gauge to SDK

* fixup! feat(instrumentation): added synchronous gauge to SDK

* fixup! feat(instrumentation): added synchronous gauge to SDK

* fixup! feat(instrumentation): added synchronous gauge to SDK

* fixup! feat(instrumentation): added synchronous gauge to SDK

* fixup! feat(instrumentation): added synchronous gauge to SDK

Author: clintonb

experimental/CHANGELOG.md

@@ -26,6 +26,7 @@ and AnyValueMap types [#4575](https://github.com/open-telemetry/opentelemetry-js
 
 ### :rocket: (Enhancement)
 
+* feat(metrics): added synchronous gauge to SDK [#4565](https://github.com/open-telemetry/opentelemetry-js/pull/4565) @clintonb
 * feat(opentelemetry-instrumentation-xhr): optionally ignore network events [#4571](https://github.com/open-telemetry/opentelemetry-js/pull/4571/) @mustafahaddara
 * refactor(instr-http): use exported strings for semconv. [#4573](https://github.com/open-telemetry/opentelemetry-js/pull/4573/) @JamieDanielson
 * perf(instrumentation-http): remove obvious temp allocations [#4576](https://github.com/open-telemetry/opentelemetry-js/pull/4576) @Samuron

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

@@ -36,6 +36,7 @@ import {
   AsyncWritableMetricStorage,
   WritableMetricStorage,
 } from './state/WritableMetricStorage';
+import { Gauge } from './types';
 
 export class SyncInstrument {
   constructor(
@@ -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,27 +25,47 @@ import {
   ObservableUpDownCounter,
   BatchObservableCallback,
   Observable,
+  Attributes,
 } from '@opentelemetry/api';
 import {
   createInstrumentDescriptor,
   InstrumentType,
 } from './InstrumentDescriptor';
 import {
   CounterInstrument,
+  GaugeInstrument,
   HistogramInstrument,
   ObservableCounterInstrument,
   ObservableGaugeInstrument,
   ObservableUpDownCounterInstrument,
   UpDownCounterInstrument,
 } from './Instruments';
 import { MeterSharedState } from './state/MeterSharedState';
+import { Gauge } from './types';
 
 /**
  * This class implements the {@link IMeter} interface.
  */
 export class Meter implements IMeter {
   constructor(private _meterSharedState: MeterSharedState) {}
 
+  /**
+   * Create a {@link Gauge} instrument.
+   * @experimental
+   */
+  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/types.ts

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { Context, MetricAttributes } from '@opentelemetry/api';
 
 export type CommonReaderOptions = {
   timeoutMillis?: number;
@@ -23,3 +24,18 @@ export type CollectionOptions = CommonReaderOptions;
 export type ShutdownOptions = CommonReaderOptions;
 
 export type ForceFlushOptions = CommonReaderOptions;
+
+/**
+ * @experimental
+ *
+ * This is intentionally not using the API's type as it's only available from @opentelemetry/api 1.9.0 and up.
+ * In SDK 2.0 we'll be able to bump the minimum API version and remove this workaround.
+ */
+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;
+}

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/Meter.test.ts

@@ -19,6 +19,7 @@ import * as assert from 'assert';
 import * as sinon from 'sinon';
 import {
   CounterInstrument,
+  GaugeInstrument,
   HistogramInstrument,
   ObservableCounterInstrument,
   ObservableGaugeInstrument,
@@ -88,6 +89,18 @@ describe('Meter', () => {
     });
   });
 
+  describe('createGauge', () => {
+    testWithNames('Gauge', name => {
+      const meterSharedState = new MeterSharedState(
+        new MeterProviderSharedState(defaultResource),
+        defaultInstrumentationScope
+      );
+      const meter = new Meter(meterSharedState);
+      const Gauge = meter.createGauge(name);
+      assert(Gauge instanceof GaugeInstrument);
+    });
+  });
+
   describe('createObservableCounter', () => {
     testWithNames('ObservableCounter', name => {
       const meterSharedState = new MeterSharedState(

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,
 ];