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

…API specification (#2496)

* feat: rename metric instruments to match feature-freeze API specification

* fixup! rename observables

* fixup!

* fixup!

* fixup!

* fixup! observable naming

* fixup! remove unnecessary spaces

* fixup! add upgrade guidelines

README.md

@@ -286,6 +286,29 @@ To request automatic tracing support for a module not on this list, please [file
 
 ## Upgrade guidelines
 
+### 0.26.x to 0.27.x
+
+Metric types are renamed:
+
+- `@openetelemetry/api-metrics`
+  - `Meter`
+    - `createValueRecorder` => `createHistogram`
+    - `createValueObserver` => `createObservableGauge`
+    - `createSumObserver` => `createObservableCounter`
+    - `createUpDownSumObserver` => `createObservableUpDownCounter`
+  - `ValueRecorder` => `Histogram`
+  - `ValueObserver` => `ObservableGauge`
+  - `SumObserver` => `ObservableCounter`
+  - `UpDownSumObserver` => `ObservableUpDownCounter`
+  - `ObserverResult` => `ObservableResult`
+  - `Observation.observer` => `Observation.observable`
+- `@opentelemetry/sdk-metrics-base`
+  - `MetricKind`
+    - `VALUE_RECORDER` => `HISTOGRAM`
+    - `SUM_OBSERVER` => `OBSERVABLE_COUNTER`
+    - `UP_DOWN_SUM_OBSERVER` => `OBSERVABLE_UP_DOWN_COUNTER`
+    - `VALUE_OBSERVER` => `OBSERVABLE_GAUGE`
+
 ### 0.25.x to 1.x.y
 
 Collector exporter packages and types are renamed:

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

@@ -21,29 +21,29 @@ const exporter = new PrometheusExporter(
 const meter = new MeterProvider({
   exporter,
   interval: 2000,
-}).getMeter('example-observer');
+}).getMeter('example-meter');
 
-meter.createValueObserver('cpu_core_usage', {
-  description: 'Example of a sync value observer with callback',
-}, async (observerResult) => { // this callback is called once per each interval
+meter.createObservableGauge('cpu_core_usage', {
+  description: 'Example of a sync observable gauge with callback',
+}, async (observableResult) => { // 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' });
+  observableResult.observe(getRandomValue(), { core: '1' });
+  observableResult.observe(getRandomValue(), { core: '2' });
 });
 
 // no callback as they will be updated in batch observer
-const tempMetric = meter.createValueObserver('cpu_temp_per_app', {
-  description: 'Example of sync value observer used with async batch observer',
+const tempMetric = meter.createObservableGauge('cpu_temp_per_app', {
+  description: 'Example of sync observable gauge used with async batch observer',
 });
 
 // no callback as they will be updated in batch observer
-const cpuUsageMetric = meter.createValueObserver('cpu_usage_per_app', {
-  description: 'Example of sync value observer used with async batch observer',
+const cpuUsageMetric = meter.createObservableGauge('cpu_usage_per_app', {
+  description: 'Example of sync observable gauge used with async batch observer',
 });
 
-meter.createBatchObserver((observerBatchResult) => {
+meter.createBatchObserver((batchObserverResult) => {
     Promise.all([
       someAsyncMetrics(),
       // simulate waiting
@@ -52,11 +52,11 @@ meter.createBatchObserver((observerBatchResult) => {
       }),
     ]).then(([apps, waiting]) => {
       apps.forEach(app => {
-        observerBatchResult.observe({ app: app.name, core: '1' }, [
+        batchObserverResult.observe({ app: app.name, core: '1' }, [
           tempMetric.observation(app.core1.temp),
           cpuUsageMetric.observation(app.core1.usage),
         ]);
-        observerBatchResult.observe({ app: app.name, core: '2' }, [
+        batchObserverResult.observe({ app: app.name, core: '2' }, [
           tempMetric.observation(app.core2.temp),
           cpuUsageMetric.observation(app.core2.usage),
         ]);

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,18 +21,19 @@ import {
   UnboundMetric,
   Labels,
   Counter,
-  ValueRecorder,
-  ValueObserver,
+  Histogram,
+  ObservableGauge,
   UpDownCounter,
-  BaseObserver,
-  UpDownSumObserver,
+  ObservableBase,
+  ObservableCounter,
+  ObservableUpDownCounter,
 } from './types/Metric';
 import {
-  BoundValueRecorder,
+  BoundHistogram,
   BoundCounter,
-  BoundBaseObserver,
+  BoundObservableBase,
 } from './types/BoundInstrument';
-import { ObserverResult } from './types/ObserverResult';
+import { ObservableResult } from './types/ObservableResult';
 import { Observation } from './types/Observation';
 
 /**
@@ -43,12 +44,12 @@ export class NoopMeter implements Meter {
   constructor() {}
 
   /**
-   * Returns constant noop value recorder.
+   * Returns a constant noop histogram.
    * @param name the name of the metric.
    * @param [options] the metric options.
    */
-  createValueRecorder(_name: string, _options?: MetricOptions): ValueRecorder {
-    return NOOP_VALUE_RECORDER_METRIC;
+  createHistogram(_name: string, _options?: MetricOptions): Histogram {
+    return NOOP_HISTOGRAM_METRIC;
   }
 
   /**
@@ -70,45 +71,45 @@ export class NoopMeter implements Meter {
   }
 
   /**
-   * Returns constant noop value observer.
+   * Returns a 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;
+    _callback?: (observableResult: ObservableResult) => void
+  ): ObservableGauge {
+    return NOOP_OBSERVABLE_GAUGE_METRIC;
   }
 
   /**
-   * Returns constant noop sum observer.
+   * Returns a constant noop observable counter.
    * @param name the name of the metric.
    * @param [options] the metric options.
-   * @param [callback] the sum observer callback
+   * @param [callback] the observable counter callback
    */
-  createSumObserver(
+  createObservableCounter(
     _name: string,
     _options?: MetricOptions,
-    _callback?: (observerResult: ObserverResult) => void
-  ): ValueObserver {
-    return NOOP_SUM_OBSERVER_METRIC;
+    _callback?: (observableResult: ObservableResult) => void
+  ): ObservableCounter {
+    return NOOP_OBSERVABLE_COUNTER_METRIC;
   }
 
   /**
-   * Returns constant noop up down sum observer.
+   * Returns a 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;
+    _callback?: (observableResult: ObservableResult) => void
+  ): 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 NoopObservableBaseMetric
+  extends NoopMetric<BoundObservableBase>
+  implements ObservableBase {
   observation(): Observation {
     return {
-      observer: this as BaseObserver,
+      observable: this as ObservableBase,
       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 NoopBoundObservableBase implements BoundObservableBase {
   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_OBSERVABLE_BASE = new NoopBoundObservableBase();
+export const NOOP_OBSERVABLE_GAUGE_METRIC = new NoopObservableBaseMetric(
+  NOOP_BOUND_OBSERVABLE_BASE
 );
 
-export const NOOP_UP_DOWN_SUM_OBSERVER_METRIC = new NoopBaseObserverMetric(
-  NOOP_BOUND_BASE_OBSERVER
+export const NOOP_OBSERVABLE_UP_DOWN_COUNTER_METRIC = new NoopObservableBaseMetric(
+  NOOP_BOUND_OBSERVABLE_BASE
 );
 
-export const NOOP_SUM_OBSERVER_METRIC = new NoopBaseObserverMetric(
-  NOOP_BOUND_BASE_OBSERVER
+export const NOOP_OBSERVABLE_COUNTER_METRIC = new NoopObservableBaseMetric(
+  NOOP_BOUND_OBSERVABLE_BASE
 );
 
 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/index.ts

@@ -22,7 +22,7 @@ export * from './types/Meter';
 export * from './types/MeterProvider';
 export * from './types/Metric';
 export * from './types/Observation';
-export * from './types/ObserverResult';
+export * from './types/ObservableResult';
 
 import { MetricsAPI } from './api/metrics';
 /** Entrypoint for metrics API */

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

@@ -18,8 +18,7 @@ import { Labels } from './Metric';
 import { Observation } from './Observation';
 
 /**
- * Interface that is being used in callback function for Observer Metric
- * for batch
+ * Interface that is being used in callback function for BatchObserver
  */
 export interface BatchObserverResult {
   /**

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 BoundObservableBase {
   update(value: number): void;
 }