feat: metric observer (open-telemetry#828)

* feat: metric observer

* chore: update after review

* chore: reviews

Co-authored-by: Mayur Kale <mayurkale@google.com>

api/package.json

@@ -18,7 +18,8 @@
     "compile": "npm run version:update && tsc -p .",
     "docs-test": "linkinator docs/out --silent --skip david-dm.org",
     "docs": "typedoc --tsconfig tsconfig.json --exclude test/**/*.ts",
-    "prepare": "npm run compile"
+    "prepare": "npm run compile",
+    "watch": "tsc -w"
   },
   "keywords": [
     "opentelemetry",

api/src/index.ts

@@ -26,6 +26,7 @@ export * from './metrics/MeterProvider';
 export * from './metrics/Metric';
 export * from './metrics/NoopMeter';
 export * from './metrics/NoopMeterProvider';
+export * from './metrics/ObserverResult';
 export * from './trace/attributes';
 export * from './trace/Event';
 export * from './trace/instrumentation/Plugin';

api/src/metrics/BoundInstrument.ts

@@ -16,6 +16,7 @@
 
 import { CorrelationContext } from '../correlation_context/CorrelationContext';
 import { SpanContext } from '../trace/span_context';
+import { ObserverResult } from './ObserverResult';
 
 /** An Instrument for Counter Metric. */
 export interface BoundCounter {
@@ -44,3 +45,14 @@ export interface BoundMeasure {
     spanContext: SpanContext
   ): void;
 }
+
+/** Base interface for the Observer metrics. */
+export interface BoundObserver {
+  /**
+   * Sets callback for the observer. The callback is called once and then it
+   * sets observers for values. The observers are called periodically to
+   * retrieve the value.
+   * @param callback
+   */
+  setCallback(callback: (observerResult: ObserverResult) => {}): void;
+}

api/src/metrics/Meter.ts

@@ -15,7 +15,7 @@
  */
 
 import { Metric, MetricOptions, Labels, LabelSet } from './Metric';
-import { BoundCounter, BoundMeasure } from './BoundInstrument';
+import { BoundCounter, BoundMeasure, BoundObserver } from './BoundInstrument';
 
 /**
  * An interface to allow the recording metrics.
@@ -33,14 +33,21 @@ export interface Meter {
   createMeasure(name: string, options?: MetricOptions): Metric<BoundMeasure>;
 
   /**
-   * Creates a new `counter` metric. Generally, this kind of metric when the
+   * Creates a new `Counter` metric. Generally, this kind of metric when the
    * value is a quantity, the sum is of primary interest, and the event count
    * and value distribution are not of primary interest.
    * @param name the name of the metric.
    * @param [options] the metric options.
    */
   createCounter(name: string, options?: MetricOptions): Metric<BoundCounter>;
 
+  /**
+   * Creates a new `Observer` metric.
+   * @param name the name of the metric.
+   * @param [options] the metric options.
+   */
+  createObserver(name: string, options?: MetricOptions): Metric<BoundObserver>;
+
   /**
    * Provide a pre-computed re-useable LabelSet by
    * converting the unordered labels into a canonicalized

api/src/metrics/Metric.ts

@@ -16,6 +16,7 @@
 
 import { CorrelationContext } from '../correlation_context/CorrelationContext';
 import { SpanContext } from '../trace/span_context';
+import { ObserverResult } from './ObserverResult';
 
 /**
  * Options needed for metric creation
@@ -105,6 +106,13 @@ export interface MetricUtils {
    */
   add(value: number, labelSet: LabelSet): void;
 
+  /**
+   * Sets a callback where user can observe value for certain labels
+   * @param callback a function that will be called once to set observers
+   *     for values
+   */
+  setCallback(callback: (observerResult: ObserverResult) => void): void;
+
   /**
    * Sets the given value. Values can be negative.
    */

api/src/metrics/NoopMeter.ts

@@ -16,9 +16,10 @@
 
 import { Meter } from './Meter';
 import { MetricOptions, Metric, Labels, LabelSet, MetricUtils } from './Metric';
-import { BoundMeasure, BoundCounter } from './BoundInstrument';
+import { BoundMeasure, BoundCounter, BoundObserver } from './BoundInstrument';
 import { CorrelationContext } from '../correlation_context/CorrelationContext';
 import { SpanContext } from '../trace/span_context';
+import { ObserverResult } from './ObserverResult';
 
 /**
  * NoopMeter is a noop implementation of the {@link Meter} interface. It reuses
@@ -45,6 +46,15 @@ export class NoopMeter implements Meter {
     return NOOP_COUNTER_METRIC;
   }
 
+  /**
+   * Returns constant noop observer.
+   * @param name the name of the metric.
+   * @param [options] the metric options.
+   */
+  createObserver(name: string, options?: MetricOptions): Metric<BoundObserver> {
+    return NOOP_OBSERVER_METRIC;
+  }
+
   labels(labels: Labels): LabelSet {
     return NOOP_LABEL_SET;
   }
@@ -120,6 +130,11 @@ export class NoopMeasureMetric extends NoopMetric<BoundMeasure>
   }
 }
 
+export class NoopObserverMetric extends NoopMetric<BoundObserver>
+  implements Pick<MetricUtils, 'setCallback'> {
+  setCallback(callback: (observerResult: ObserverResult) => void): void {}
+}
+
 export class NoopBoundCounter implements BoundCounter {
   add(value: number): void {
     return;
@@ -136,11 +151,18 @@ export class NoopBoundMeasure implements BoundMeasure {
   }
 }
 
+export class NoopBoundObserver implements BoundObserver {
+  setCallback(callback: (observerResult: ObserverResult) => {}): void {}
+}
+
 export const NOOP_METER = new NoopMeter();
 export const NOOP_BOUND_COUNTER = new NoopBoundCounter();
 export const NOOP_COUNTER_METRIC = new NoopCounterMetric(NOOP_BOUND_COUNTER);
 
 export const NOOP_BOUND_MEASURE = new NoopBoundMeasure();
 export const NOOP_MEASURE_METRIC = new NoopMeasureMetric(NOOP_BOUND_MEASURE);
 
+export const NOOP_BOUND_OBSERVER = new NoopBoundObserver();
+export const NOOP_OBSERVER_METRIC = new NoopObserverMetric(NOOP_BOUND_OBSERVER);
+
 export const NOOP_LABEL_SET = {} as LabelSet;

api/src/metrics/ObserverResult.ts

@@ -0,0 +1,25 @@
+/*!
+ * Copyright 2020, 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 { LabelSet } from './Metric';
+
+/**
+ * Interface that is being used in function setCallback for Observer Metric
+ */
+export interface ObserverResult {
+  observers: Map<LabelSet, Function>;
+  observe(callback: Function, labelSet: LabelSet): void;
+}