[prototype] feat(api): add wrapMeter() for experimental metrics API features

api/CHANGELOG.md

@@ -8,6 +8,7 @@ All notable changes to this project will be documented in this file.
 
 ### :rocket: (Enhancement)
 
+* feat(metrics): added synchronous gauge [#4528](https://github.com/open-telemetry/opentelemetry-js/pull/4528) @clintonb
 * feat: support node 22 [#4666](https://github.com/open-telemetry/opentelemetry-js/pull/4666) @dyladan
 
 ### :bug: (Bug Fix)

api/package.json

@@ -26,6 +26,16 @@
       "default": "./build/src/experimental/index.js"
     }
   },
+  "typesVersions": {
+    "<4.9": {
+      "*": [
+        "./build/src/index.d.ts"
+      ],
+      "experimental": [
+        "./build/src/experimental/index.d.ts"
+      ]
+    }
+  },
   "repository": "open-telemetry/opentelemetry-js",
   "scripts": {
     "clean": "tsc --build --clean tsconfig.json tsconfig.esm.json tsconfig.esnext.json",

api/src/experimental/index.ts

@@ -13,5 +13,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
+// Trace
 export { wrapTracer, SugaredTracer } from './trace/SugaredTracer';
 export { SugaredSpanOptions } from './trace/SugaredOptions';
+
+// Metrics
+export {
+  wrapMeter,
+  Gauge,
+  IExperimentalMeter,
+} from './metrics/ExperimentalMeter';

api/src/experimental/metrics/ExperimentalMeter.ts

@@ -0,0 +1,129 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Meter } from '../../metrics/Meter';
+import { MetricAttributes, MetricOptions } from '../../metrics/Metric';
+import { Context } from '../../context/types';
+import { NOOP_GAUGE_METRIC } from './Gauge';
+
+/**
+ * @experimental
+ *
+ * Records only the last value that is added to it, discards any others.
+ */
+export interface Gauge<
+  AttributesTypes extends MetricAttributes = MetricAttributes,
+> {
+  /**
+   * @experimental
+   * Records a measurement.
+   */
+  record(value: number, attributes?: AttributesTypes, context?: Context): void;
+}
+
+/**
+ * Steps for adding new experimental Meter API features:
+ * - implement the specification in the `@opentelemetry/sdk-metrics` package, do NOT use any new types
+ *   - SDKs may peer-depend on old API versions where these types are not yet available
+ *   - we MUST duplicate any new types across API and SDK unless we drop support for older API versions
+ *     - dropping support for old API versions MUST be done in SDK Major versions
+ *     - failure to do this will result in failing builds for users that update the SDK but not the API
+ * - add the new functionality to the {@link IExperimentalMeter} interface
+ * - implement the functionality in the {@link ExperimentalMeter}
+ *   - if the underlying {@link Meter} used as an {@link IExperimentalMeter} throws an error, return a No-Op implementation.
+ *
+ * Users may now use {@link wrapMeter} to get access to experimental SDK functionality via the API
+ *
+ * To stabilize a feature:
+ * - move the function interface from `IExperimentalMeter` to `Meter`
+ * - replace the implemented method with a property of the same type as the one from `Meter`, move any auxiliary types to stable
+ * - In ExperimentalMeter
+ *   - remove the implementation that falls back to No-Op on errors.
+ *   - assign the function that was moved to `Meter` to the property defined in the last step
+ * - Implement the no-op case in {@link NoopMeter}
+ * - ensure any `@experimental` annotations are removed
+ */
+
+/**
+ * @experimental
+ *
+ * Meter that offers experimental functionality IF that functionality is implemented by the SDK.
+ * MAY return a no-op otherwise. Stable features continue to work as expected.
+ */
+export interface IExperimentalMeter extends Meter {
+  /**
+   * @experimental Will be added to {@link Meter} in a future version when the specification is marked stable
+   *
+   * 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>;
+}
+
+class ExperimentalMeter implements IExperimentalMeter {
+  private _meter: Meter;
+  constructor(meter: Meter) {
+    this._meter = meter;
+    this.addBatchObservableCallback =
+      meter.addBatchObservableCallback.bind(meter);
+    this.createCounter = meter.createCounter.bind(meter);
+    this.createObservableGauge = meter.createObservableGauge.bind(meter);
+    this.createHistogram = meter.createHistogram.bind(meter);
+    this.createObservableCounter = meter.createObservableCounter.bind(meter);
+    this.createObservableUpDownCounter =
+      meter.createObservableUpDownCounter.bind(meter);
+    this.createUpDownCounter = meter.createUpDownCounter.bind(meter);
+    this.removeBatchObservableCallback =
+      meter.removeBatchObservableCallback.bind(meter);
+  }
+  addBatchObservableCallback: Meter['addBatchObservableCallback'];
+  createCounter: Meter['createCounter'];
+  createObservableGauge: Meter['createObservableGauge'];
+  createHistogram: Meter['createHistogram'];
+  createObservableCounter: Meter['createObservableCounter'];
+  createUpDownCounter: Meter['createUpDownCounter'];
+  createObservableUpDownCounter: Meter['createObservableUpDownCounter'];
+  removeBatchObservableCallback: Meter['removeBatchObservableCallback'];
+
+  /**
+   * Creates and returns a new `Gauge`.
+   * @param name the name of the metric.
+   * @param [options] the metric options.
+   */
+  createGauge(name: string, options?: MetricOptions): Gauge {
+    try {
+      return (this._meter as ExperimentalMeter).createGauge(name, options);
+    } catch (e) {
+      return NOOP_GAUGE_METRIC;
+    }
+  }
+}
+
+/**
+ * @experimental
+ *
+ * Wraps {@link Meter} so that it offers experimental functionality IF that functionality is implemented by the
+ * registered SDK. MAY return a no-op instrument if the functionality is not implemented by the SDK.
+ * Stable features continue to work as expected.
+ *
+ * @param meter
+ */
+export function wrapMeter(meter: Meter): IExperimentalMeter {
+  return new ExperimentalMeter(meter);
+}

api/src/experimental/metrics/Gauge.ts

@@ -0,0 +1,31 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Gauge } from './ExperimentalMeter';
+import { MetricAttributes } from '../../metrics/Metric';
+import { NoopMetric } from '../../metrics/NoopMeter';
+
+/**
+ * @experimental
+ */
+export class NoopGaugeMetric extends NoopMetric implements Gauge {
+  record(_value: number, _attributes: MetricAttributes): void {}
+}
+
+/**
+ * @experimental
+ */
+export const NOOP_GAUGE_METRIC = new NoopGaugeMetric();

api/src/metrics/NoopMeter.ts

@@ -19,14 +19,14 @@ import {
   BatchObservableCallback,
   Counter,
   Histogram,
+  MetricAttributes,
   MetricOptions,
+  Observable,
   ObservableCallback,
   ObservableCounter,
   ObservableGauge,
   ObservableUpDownCounter,
   UpDownCounter,
-  MetricAttributes,
-  Observable,
 } from './Metric';
 
 /**

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

@@ -26,6 +26,8 @@ import {
   createNoopMeter,
 } from '../../../src/metrics/NoopMeter';
 import { NoopMeterProvider } from '../../../src/metrics/NoopMeterProvider';
+import { wrapMeter } from '../../../src/experimental';
+import { NOOP_GAUGE_METRIC } from '../../../src/experimental/metrics/Gauge';
 
 const attributes = {};
 const options = {
@@ -116,6 +118,17 @@ describe('NoopMeter', () => {
     );
   });
 
+  it('gauge should not crash', () => {
+    const meter = new NoopMeterProvider().getMeter('test-noop');
+    const observableGauge = wrapMeter(meter).createGauge('some-name');
+
+    // ensure the correct noop const is returned
+    assert.strictEqual(observableGauge, NOOP_GAUGE_METRIC);
+
+    const gaugeWithOptions = wrapMeter(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 =

packages/sdk-metrics/test/Instruments.test.ts

@@ -19,27 +19,28 @@ import * as sinon from 'sinon';
 import { InstrumentationScope } from '@opentelemetry/core';
 import { Resource } from '@opentelemetry/resources';
 import {
-  InstrumentType,
-  MeterProvider,
-  MetricReader,
   DataPoint,
   DataPointType,
   Histogram,
+  InstrumentType,
+  MeterProvider,
   MetricDescriptor,
+  MetricReader,
 } from '../src';
 import {
   TestDeltaMetricReader,
   TestMetricReader,
 } from './export/TestMetricReader';
 import {
-  assertMetricData,
   assertDataPoint,
-  commonValues,
+  assertMetricData,
   commonAttributes,
-  defaultResource,
+  commonValues,
   defaultInstrumentationScope,
+  defaultResource,
 } from './util';
 import { ObservableResult, ValueType } from '@opentelemetry/api';
+import { wrapMeter } from '@opentelemetry/api/experimental';
 
 describe('Instruments', () => {
   describe('Counter', () => {
@@ -764,6 +765,41 @@ describe('Instruments', () => {
       });
     });
   });
+
+  describe('Gauge', () => {
+    it('should record common values and attributes without exceptions', async () => {
+      const { meter } = setup();
+      const gauge = wrapMeter(meter).createGauge('test');
+
+      for (const values of commonValues) {
+        for (const attributes of commonAttributes) {
+          gauge.record(values, attributes);
+        }
+      }
+    });
+
+    it('should record values', async () => {
+      const { meter, cumulativeReader } = setup();
+      const gauge = wrapMeter(meter).createGauge('test');
+
+      gauge.record(1, { foo: 'bar' });
+      gauge.record(-1);
+
+      await validateExport(cumulativeReader, {
+        dataPointType: DataPointType.GAUGE,
+        dataPoints: [
+          {
+            attributes: { foo: 'bar' },
+            value: 1,
+          },
+          {
+            attributes: {},
+            value: -1,
+          },
+        ],
+      });
+    });
+  });
 });
 
 function setup() {