feat(api-metrics): rename metric instruments to match feature-freeze API specification

doc/processor-api.md

@@ -138,7 +138,7 @@ const meter = new MeterProvider({
   interval: 1000,
 }).getMeter('example-custom-processor');
 
-const requestsLatency = meter.createValueRecorder('requests', {
+const requestsLatency = meter.createHistogram('requests', {
   monotonic: true,
   description: 'Average latency'
 });

examples/metrics/metrics/observer.js

@@ -23,7 +23,7 @@ const meter = new MeterProvider({
   interval: 2000,
 }).getMeter('example-observer');
 
-meter.createValueObserver('cpu_core_usage', {
+meter.createObservableGauge('cpu_core_usage', {
   description: 'Example of a sync value observer with callback',
 }, async (observerResult) => { // this callback is called once per each interval
   await new Promise((resolve) => {
@@ -34,12 +34,12 @@ meter.createValueObserver('cpu_core_usage', {
 });
 
 // no callback as they will be updated in batch observer
-const tempMetric = meter.createValueObserver('cpu_temp_per_app', {
+const tempMetric = meter.createObservableGauge('cpu_temp_per_app', {
   description: 'Example of sync value observer used with async batch observer',
 });
 
 // no callback as they will be updated in batch observer
-const cpuUsageMetric = meter.createValueObserver('cpu_usage_per_app', {
+const cpuUsageMetric = meter.createObservableGauge('cpu_usage_per_app', {
   description: 'Example of sync value observer used with async batch observer',
 });
 

examples/otlp-exporter-node/metrics.js

@@ -31,14 +31,14 @@ const upDownCounter = meter.createUpDownCounter('test_up_down_counter', {
   description: 'Example of a UpDownCounter',
 });
 
-const recorder = meter.createValueRecorder('test_value_recorder', {
-  description: 'Example of a ValueRecorder',
+const histogram = meter.createHistogram('test_histogram', {
+  description: 'Example of a Histogram',
 });
 
 const labels = { pid: process.pid, environment: 'staging' };
 
 setInterval(() => {
   requestCounter.bind(labels).add(1);
   upDownCounter.bind(labels).add(Math.random() > 0.5 ? 1 : -1);
-  recorder.bind(labels).record(Math.random());
+  histogram.bind(labels).record(Math.random());
 }, 1000);

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

@@ -21,16 +21,17 @@ import {
   UnboundMetric,
   Labels,
   Counter,
-  ValueRecorder,
-  ValueObserver,
+  Histogram,
+  ObservableGauge,
   UpDownCounter,
-  BaseObserver,
-  UpDownSumObserver,
+  BaseObservable,
+  ObservableCounter,
+  ObservableUpDownCounter,
 } from './types/Metric';
 import {
-  BoundValueRecorder,
+  BoundHistogram,
   BoundCounter,
-  BoundBaseObserver,
+  BoundBaseObservable,
 } from './types/BoundInstrument';
 import { ObserverResult } from './types/ObserverResult';
 import { Observation } from './types/Observation';
@@ -43,72 +44,72 @@ export class NoopMeter implements Meter {
   constructor() {}
 
   /**
-   * Returns constant noop value recorder.
+   * Returns a constant noop counter.
    * @param name the name of the metric.
    * @param [options] the metric options.
    */
-  createValueRecorder(_name: string, _options?: MetricOptions): ValueRecorder {
-    return NOOP_VALUE_RECORDER_METRIC;
+   createCounter(_name: string, _options?: MetricOptions): Counter {
+    return NOOP_COUNTER_METRIC;
   }
 
   /**
-   * Returns a constant noop counter.
+   * Returns constant noop observable counter.
    * @param name the name of the metric.
    * @param [options] the metric options.
+   * @param [callback] the observable counter callback
    */
-  createCounter(_name: string, _options?: MetricOptions): Counter {
-    return NOOP_COUNTER_METRIC;
+  createObservableCounter(
+    _name: string,
+    _options?: MetricOptions,
+    _callback?: (observerResult: ObserverResult) => void
+  ): ObservableCounter {
+    return NOOP_OBSERVABLE_COUNTER_METRIC;
   }
 
   /**
-   * Returns a constant noop UpDownCounter.
+   * Returns constant noop histogram.
    * @param name the name of the metric.
    * @param [options] the metric options.
    */
-  createUpDownCounter(_name: string, _options?: MetricOptions): UpDownCounter {
-    return NOOP_COUNTER_METRIC;
+  createHistogram(_name: string, _options?: MetricOptions): Histogram {
+    return NOOP_HISTOGRAM_METRIC;
   }
 
   /**
-   * Returns constant noop value observer.
+   * Returns constant noop observable gauge.
    * @param name the name of the metric.
    * @param [options] the metric options.
-   * @param [callback] the value observer callback
+   * @param [callback] the observable gauge callback
    */
-  createValueObserver(
+  createObservableGauge(
     _name: string,
     _options?: MetricOptions,
     _callback?: (observerResult: ObserverResult) => void
-  ): ValueObserver {
-    return NOOP_VALUE_OBSERVER_METRIC;
+  ): ObservableGauge {
+    return NOOP_OBSERVABLE_GAUGE_METRIC;
   }
 
   /**
-   * Returns constant noop sum observer.
+   * Returns a constant noop UpDownCounter.
    * @param name the name of the metric.
    * @param [options] the metric options.
-   * @param [callback] the sum observer callback
    */
-  createSumObserver(
-    _name: string,
-    _options?: MetricOptions,
-    _callback?: (observerResult: ObserverResult) => void
-  ): ValueObserver {
-    return NOOP_SUM_OBSERVER_METRIC;
+  createUpDownCounter(_name: string, _options?: MetricOptions): UpDownCounter {
+    return NOOP_COUNTER_METRIC;
   }
 
   /**
-   * Returns constant noop up down sum observer.
+   * Returns constant noop up down observable counter.
    * @param name the name of the metric.
    * @param [options] the metric options.
-   * @param [callback] the up down sum observer callback
+   * @param [callback] the up down observable counter callback
    */
-  createUpDownSumObserver(
+  createObservableUpDownCounter(
     _name: string,
     _options?: MetricOptions,
     _callback?: (observerResult: ObserverResult) => void
-  ): UpDownSumObserver {
-    return NOOP_UP_DOWN_SUM_OBSERVER_METRIC;
+  ): ObservableUpDownCounter {
+    return NOOP_OBSERVABLE_UP_DOWN_COUNTER_METRIC;
   }
 
   /**
@@ -165,20 +166,20 @@ export class NoopCounterMetric
   }
 }
 
-export class NoopValueRecorderMetric
-  extends NoopMetric<BoundValueRecorder>
-  implements ValueRecorder {
+export class NoopHistogramMetric
+  extends NoopMetric<BoundHistogram>
+  implements Histogram {
   record(value: number, labels: Labels): void {
     this.bind(labels).record(value);
   }
 }
 
-export class NoopBaseObserverMetric
-  extends NoopMetric<BoundBaseObserver>
-  implements BaseObserver {
+export class NoopBaseObservableMetric
+  extends NoopMetric<BoundBaseObservable>
+  implements BaseObservable {
   observation(): Observation {
     return {
-      observer: this as BaseObserver,
+      observer: this as BaseObservable,
       value: 0,
     };
   }
@@ -192,36 +193,36 @@ export class NoopBoundCounter implements BoundCounter {
   }
 }
 
-export class NoopBoundValueRecorder implements BoundValueRecorder {
+export class NoopBoundHistogram implements BoundHistogram {
   record(_value: number, _baggage?: unknown, _spanContext?: unknown): void {
     return;
   }
 }
 
-export class NoopBoundBaseObserver implements BoundBaseObserver {
+export class NoopBoundBaseObservable implements BoundBaseObservable {
   update(_value: number): 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_VALUE_RECORDER = new NoopBoundValueRecorder();
-export const NOOP_VALUE_RECORDER_METRIC = new NoopValueRecorderMetric(
-  NOOP_BOUND_VALUE_RECORDER
+export const NOOP_BOUND_HISTOGRAM = new NoopBoundHistogram();
+export const NOOP_HISTOGRAM_METRIC = new NoopHistogramMetric(
+  NOOP_BOUND_HISTOGRAM
 );
 
-export const NOOP_BOUND_BASE_OBSERVER = new NoopBoundBaseObserver();
-export const NOOP_VALUE_OBSERVER_METRIC = new NoopBaseObserverMetric(
-  NOOP_BOUND_BASE_OBSERVER
+export const NOOP_BOUND_BASE_OBSERVABLE = new NoopBoundBaseObservable();
+export const NOOP_OBSERVABLE_GAUGE_METRIC = new NoopBaseObservableMetric(
+  NOOP_BOUND_BASE_OBSERVABLE
 );
 
-export const NOOP_UP_DOWN_SUM_OBSERVER_METRIC = new NoopBaseObserverMetric(
-  NOOP_BOUND_BASE_OBSERVER
+export const NOOP_OBSERVABLE_UP_DOWN_COUNTER_METRIC = new NoopBaseObservableMetric(
+  NOOP_BOUND_BASE_OBSERVABLE
 );
 
-export const NOOP_SUM_OBSERVER_METRIC = new NoopBaseObserverMetric(
-  NOOP_BOUND_BASE_OBSERVER
+export const NOOP_OBSERVABLE_COUNTER_METRIC = new NoopBaseObservableMetric(
+  NOOP_BOUND_BASE_OBSERVABLE
 );
 
 export const NOOP_BATCH_OBSERVER = new NoopBatchObserver();

experimental/packages/opentelemetry-api-metrics/src/api/global-utils.ts

@@ -52,4 +52,4 @@ export function makeGetter<T>(
  * version. If the global API is not compatible with the API package
  * attempting to get it, a NOOP API implementation will be returned.
  */
-export const API_BACKWARDS_COMPATIBILITY_VERSION = 3;
+export const API_BACKWARDS_COMPATIBILITY_VERSION = 4;

experimental/packages/opentelemetry-api-metrics/src/types/BoundInstrument.ts

@@ -23,16 +23,16 @@ export interface BoundCounter {
   add(value: number): void;
 }
 
-/** ValueRecorder to report instantaneous measurement of a value. */
-export interface BoundValueRecorder {
+/** Histogram to report instantaneous measurement of a value. */
+export interface BoundHistogram {
   /**
-   * Records the given value to this value recorder.
+   * Records the given value to this histogram.
    * @param value to record.
    */
   record(value: number): void;
 }
 
-/** An Instrument for Base Observer */
-export interface BoundBaseObserver {
+/** An Instrument for Base Observable */
+export interface BoundBaseObservable {
   update(value: number): void;
 }

experimental/packages/opentelemetry-api-metrics/src/types/Meter.ts

@@ -18,38 +18,62 @@ import { BatchObserverResult } from './BatchObserverResult';
 import {
   MetricOptions,
   Counter,
-  ValueRecorder,
-  ValueObserver,
+  Histogram,
+  ObservableGauge,
   BatchObserverOptions,
   UpDownCounter,
-  SumObserver,
-  UpDownSumObserver,
+  ObservableCounter,
+  ObservableUpDownCounter,
 } from './Metric';
 import { ObserverResult } from './ObserverResult';
 
 /**
  * An interface to allow the recording metrics.
  *
  * {@link Metric}s are used for recording pre-defined aggregation (`Counter`),
- * or raw values (`ValueRecorder`) in which the aggregation and labels
+ * or raw values (`Histogram`) in which the aggregation and labels
  * for the exported metric are deferred.
  */
 export interface Meter {
   /**
-   * Creates and returns a new `ValueRecorder`.
+   * 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.
    */
-  createValueRecorder(name: string, options?: MetricOptions): ValueRecorder;
+  createCounter(name: string, options?: MetricOptions): Counter;
 
   /**
-   * 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.
+   * Creates a new `ObservableCounter` metric.
    * @param name the name of the metric.
    * @param [options] the metric options.
+   * @param [callback] the observable callback
    */
-  createCounter(name: string, options?: MetricOptions): Counter;
+  createObservableCounter(
+    name: string,
+    options?: MetricOptions,
+    callback?: (observerResult: ObserverResult) => void
+  ): ObservableCounter;
+
+  /**
+   * Creates and returns a new `Histogram`.
+   * @param name the name of the metric.
+   * @param [options] the metric options.
+   */
+  createHistogram(name: string, options?: MetricOptions): Histogram;
+
+  /**
+   * Creates a new `ObservableGauge` metric.
+   * @param name the name of the metric.
+   * @param [options] the metric options.
+   * @param [callback] the observable callback
+   */
+   createObservableGauge(
+    name: string,
+    options?: MetricOptions,
+    callback?: (observerResult: ObserverResult) => void
+  ): ObservableGauge;
 
   /**
    * Creates a new `UpDownCounter` metric. UpDownCounter is a synchronous
@@ -71,40 +95,16 @@ export interface Meter {
   createUpDownCounter(name: string, options?: MetricOptions): UpDownCounter;
 
   /**
-   * Creates a new `ValueObserver` metric.
-   * @param name the name of the metric.
-   * @param [options] the metric options.
-   * @param [callback] the observer callback
-   */
-  createValueObserver(
-    name: string,
-    options?: MetricOptions,
-    callback?: (observerResult: ObserverResult) => void
-  ): ValueObserver;
-
-  /**
-   * Creates a new `SumObserver` metric.
-   * @param name the name of the metric.
-   * @param [options] the metric options.
-   * @param [callback] the observer callback
-   */
-  createSumObserver(
-    name: string,
-    options?: MetricOptions,
-    callback?: (observerResult: ObserverResult) => void
-  ): SumObserver;
-
-  /**
-   * Creates a new `UpDownSumObserver` metric.
+   * Creates a new `ObservableUpDownCounter` metric.
    * @param name the name of the metric.
    * @param [options] the metric options.
-   * @param [callback] the observer callback
+   * @param [callback] the observable callback
    */
-  createUpDownSumObserver(
+  createObservableUpDownCounter(
     name: string,
     options?: MetricOptions,
     callback?: (observerResult: ObserverResult) => void
-  ): UpDownSumObserver;
+  ): ObservableUpDownCounter;
 
   /**
    * Creates a new `BatchObserver`, can be used to update many metrics