feat: adding new metric: up down sum observer (open-telemetry#1272)

Co-authored-by: Mayur Kale <[email protected]>

Author: obecny

examples/metrics/metrics/observer.js

@@ -22,7 +22,10 @@ const meter = new MeterProvider({
 
 meter.createValueObserver('cpu_core_usage', {
   description: 'Example of a sync value observer with callback',
-}, (observerResult) => { // this callback is called once per each interval
+}, async (observerResult) => { // this callback is called once per each interval
+  await new Promise((resolve) => {
+    setTimeout(()=> {resolve()}, 50);
+  });
   observerResult.observe(getRandomValue(), { core: '1' });
   observerResult.observe(getRandomValue(), { core: '2' });
 });

packages/opentelemetry-api/src/metrics/Metric.ts

@@ -173,9 +173,12 @@ export interface BaseObserver extends UnboundMetric<BoundBaseObserver> {
   };
 }
 
-/** Base interface for the Value Observer metrics. */
+/** Base interface for the ValueObserver metrics. */
 export type ValueObserver = BaseObserver;
 
+/** Base interface for the UpDownSumObserver metrics. */
+export type UpDownSumObserver = BaseObserver;
+
 /** Base interface for the Batch Observer metrics. */
 export type BatchObserver = Metric;
 

packages/opentelemetry-api/src/metrics/NoopMeter.ts

@@ -202,4 +202,7 @@ export const NOOP_BOUND_BASE_OBSERVER = new NoopBoundBaseObserver();
 export const NOOP_VALUE_OBSERVER_METRIC = new NoopBaseObserverMetric(
   NOOP_BOUND_BASE_OBSERVER
 );
+export const NOOP_UP_DOWN_SUM_OBSERVER_METRIC = new NoopBaseObserverMetric(
+  NOOP_BOUND_BASE_OBSERVER
+);
 export const NOOP_BATCH_OBSERVER_METRIC = new NoopBatchObserverMetric();

packages/opentelemetry-metrics/README.md

@@ -76,18 +76,75 @@ boundCounter.add(Math.random() > 0.5 ? 1 : -1);
 
 ### Value Observer
 
-Choose this kind of metric when only last value is important without worry about aggregation
+Choose this kind of metric when only last value is important without worry about aggregation.
+The callback can be sync or async.
 
 ```js
 const { MeterProvider } = require('@opentelemetry/metrics');
 
 const meter = new MeterProvider().getMeter('your-meter-name');
 
-meter.createValueObserver('cpu_core_usage', {
+
+// async callback - for operation that needs to wait for value
+meter.createValueObserver('your_metric_name', {
+  description: 'Example of an async observer with callback',
+}, async (observerResult) => {
+  const value = await getAsyncValue();
+  observerResult.observe(value, { label: '1' });
+});
+
+function getAsyncValue() {
+  return new Promise((resolve) => {
+    setTimeout(()=> {
+      resolve(Math.random());
+    }, 100);
+  });
+}
+
+// sync callback in case you don't need to wait for value
+meter.createValueObserver('your_metric_name', {
+  description: 'Example of a sync observer with callback',
+}, (observerResult) => {
+  observerResult.observe(getRandomValue(), { label: '1' });
+  observerResult.observe(getRandomValue(), { label: '2' });
+});
+
+function getRandomValue() {
+  return Math.random();
+}
+```
+
+### UpDownSumObserver
+
+Choose this kind of metric when sum is important and you want to capture any value that starts at zero and rises or falls throughout the process lifetime.
+The callback can be sync or async.
+
+```js
+const { MeterProvider } = require('@opentelemetry/metrics');
+
+const meter = new MeterProvider().getMeter('your-meter-name');
+
+// async callback - for operation that needs to wait for value
+meter.createUpDownSumObserver('your_metric_name', {
+  description: 'Example of an async observer with callback',
+}, async (observerResult) => {
+  const value = await getAsyncValue();
+  observerResult.observe(value, { label: '1' });
+});
+
+function getAsyncValue() {
+  return new Promise((resolve) => {
+    setTimeout(()=> {
+      resolve(Math.random());
+    }, 100);
+  });
+}
+
+// sync callback in case you don't need to wait for value
+meter.createUpDownSumObserver('your_metric_name', {
   description: 'Example of a sync observer with callback',
 }, (observerResult) => {
-  observerResult.observe(getRandomValue(), { core: '1' });
-  observerResult.observe(getRandomValue(), { core: '2' });
+  observerResult.observe(getRandomValue(), { label: '1' });
 });
 
 function getRandomValue() {

packages/opentelemetry-metrics/src/BaseObserverMetric.ts

@@ -30,7 +30,7 @@ const NOOP_CALLBACK = () => {};
  */
 export abstract class BaseObserverMetric extends Metric<BoundObserver>
   implements api.BaseObserver {
-  protected _callback: (observerResult: api.ObserverResult) => void;
+  protected _callback: (observerResult: api.ObserverResult) => unknown;
 
   constructor(
     name: string,
@@ -39,7 +39,7 @@ export abstract class BaseObserverMetric extends Metric<BoundObserver>
     resource: Resource,
     metricKind: MetricKind,
     instrumentationLibrary: InstrumentationLibrary,
-    callback?: (observerResult: api.ObserverResult) => void
+    callback?: (observerResult: api.ObserverResult) => unknown
   ) {
     super(name, options, metricKind, resource, instrumentationLibrary);
     this._callback = callback || NOOP_CALLBACK;
@@ -55,9 +55,9 @@ export abstract class BaseObserverMetric extends Metric<BoundObserver>
     );
   }
 
-  getMetricRecord(): Promise<MetricRecord[]> {
+  async getMetricRecord(): Promise<MetricRecord[]> {
     const observerResult = new ObserverResult();
-    this._callback(observerResult);
+    await this._callback(observerResult);
     observerResult.values.forEach((value, labels) => {
       const instrument = this.bind(labels);
       instrument.update(value);

packages/opentelemetry-metrics/src/Meter.ts

@@ -21,6 +21,7 @@ import { BatchObserverMetric } from './BatchObserverMetric';
 import { BaseBoundInstrument } from './BoundInstrument';
 import { UpDownCounterMetric } from './UpDownCounterMetric';
 import { CounterMetric } from './CounterMetric';
+import { UpDownSumObserverMetric } from './UpDownSumObserverMetric';
 import { ValueRecorderMetric } from './ValueRecorderMetric';
 import { Metric } from './Metric';
 import { ValueObserverMetric } from './ValueObserverMetric';
@@ -156,15 +157,15 @@ export class Meter implements api.Meter {
   }
 
   /**
-   * Creates a new value observer metric.
+   * Creates a new `ValueObserver` metric.
    * @param name the name of the metric.
    * @param [options] the metric options.
    * @param [callback] the value observer callback
    */
   createValueObserver(
     name: string,
     options: api.MetricOptions = {},
-    callback?: (observerResult: api.ObserverResult) => void
+    callback?: (observerResult: api.ObserverResult) => unknown
   ): api.ValueObserver {
     if (!this._isValidName(name)) {
       this._logger.warn(
@@ -189,6 +190,40 @@ export class Meter implements api.Meter {
     return valueObserver;
   }
 
+  /**
+   * Creates a new `UpDownSumObserver` metric.
+   * @param name the name of the metric.
+   * @param [options] the metric options.
+   * @param [callback] the value observer callback
+   */
+  createUpDownSumObserver(
+    name: string,
+    options: api.MetricOptions = {},
+    callback?: (observerResult: api.ObserverResult) => unknown
+  ): api.UpDownSumObserver {
+    if (!this._isValidName(name)) {
+      this._logger.warn(
+        `Invalid metric name ${name}. Defaulting to noop metric implementation.`
+      );
+      return api.NOOP_UP_DOWN_SUM_OBSERVER_METRIC;
+    }
+    const opt: api.MetricOptions = {
+      logger: this._logger,
+      ...DEFAULT_METRIC_OPTIONS,
+      ...options,
+    };
+    const upDownSumObserver = new UpDownSumObserverMetric(
+      name,
+      opt,
+      this._batcher,
+      this._resource,
+      this._instrumentationLibrary,
+      callback
+    );
+    this._registerMetric(name, upDownSumObserver);
+    return upDownSumObserver;
+  }
+
   /**
    * Creates a new batch observer metric.
    * @param name the name of the metric.

packages/opentelemetry-metrics/src/UpDownSumObserverMetric.ts

@@ -0,0 +1,45 @@
+/*
+ * 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 * as api from '@opentelemetry/api';
+import { InstrumentationLibrary } from '@opentelemetry/core';
+import { Resource } from '@opentelemetry/resources';
+import { BaseObserverMetric } from './BaseObserverMetric';
+import { Batcher } from './export/Batcher';
+import { MetricKind } from './export/types';
+
+/** This is a SDK implementation of UpDownSumObserver Metric. */
+export class UpDownSumObserverMetric extends BaseObserverMetric
+  implements api.UpDownSumObserver {
+  constructor(
+    name: string,
+    options: api.MetricOptions,
+    batcher: Batcher,
+    resource: Resource,
+    instrumentationLibrary: InstrumentationLibrary,
+    callback?: (observerResult: api.ObserverResult) => unknown
+  ) {
+    super(
+      name,
+      options,
+      batcher,
+      resource,
+      MetricKind.UP_DOWN_SUM_OBSERVER,
+      instrumentationLibrary,
+      callback
+    );
+  }
+}

packages/opentelemetry-metrics/src/ValueObserverMetric.ts

@@ -29,7 +29,7 @@ export class ValueObserverMetric extends BaseObserverMetric
     batcher: Batcher,
     resource: Resource,
     instrumentationLibrary: InstrumentationLibrary,
-    callback?: (observerResult: api.ObserverResult) => void
+    callback?: (observerResult: api.ObserverResult) => unknown
   ) {
     super(
       name,