chore: rename meaure to value recorder (open-telemetry#1117)

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

@@ -26,15 +26,15 @@ export interface BoundCounter {
   add(value: number): void;
 }
 
-/** Measure to report instantaneous measurement of a value. */
-export interface BoundMeasure {
+/** ValueRecorder to report instantaneous measurement of a value. */
+export interface BoundValueRecorder {
   /**
-   * Records the given value to this measure.
-   * @param value the measurement to record.
+   * Records the given value to this value recorder.
+   * @param value to record.
    * @param correlationContext the correlationContext associated with the
-   *     measurements.
+   *     values.
    * @param spanContext the {@link SpanContext} that identifies the {@link Span}
-   *     for which the measurements are associated with.
+   *     which the values are associated with.
    */
   record(value: number): void;
   record(value: number, correlationContext: CorrelationContext): void;

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

@@ -14,22 +14,22 @@
  * limitations under the License.
  */
 
-import { MetricOptions, Counter, Measure, Observer } from './Metric';
+import { MetricOptions, Counter, ValueRecorder, Observer } from './Metric';
 
 /**
  * An interface to allow the recording metrics.
  *
  * {@link Metric}s are used for recording pre-defined aggregation (`Counter`),
- * or raw values (`Measure`) in which the aggregation and labels
+ * or raw values (`ValueRecorder`) in which the aggregation and labels
  * for the exported metric are deferred.
  */
 export interface Meter {
   /**
-   * Creates and returns a new `Measure`.
+   * Creates and returns a new `ValueRecorder`.
    * @param name the name of the metric.
    * @param [options] the metric options.
    */
-  createMeasure(name: string, options?: MetricOptions): Measure;
+  createValueRecorder(name: string, options?: MetricOptions): ValueRecorder;
 
   /**
    * Creates a new `Counter` metric. Generally, this kind of metric when the

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

@@ -17,7 +17,7 @@
 import { CorrelationContext } from '../correlation_context/CorrelationContext';
 import { SpanContext } from '../trace/span_context';
 import { ObserverResult } from './ObserverResult';
-import { BoundCounter, BoundMeasure } from './BoundInstrument';
+import { BoundCounter, BoundValueRecorder } from './BoundInstrument';
 
 /**
  * Options needed for metric creation
@@ -56,7 +56,7 @@ export interface MetricOptions {
   monotonic?: boolean;
 
   /**
-   * (Measure only, default true) Asserts that this metric will only accept
+   * (ValueRecorder only, default true) Asserts that this metric will only accept
    * non-negative values (e.g. disk usage).
    */
   absolute?: boolean;
@@ -128,9 +128,9 @@ export interface Counter extends UnboundMetric<BoundCounter> {
   add(value: number, labels?: Labels): void;
 }
 
-export interface Measure extends UnboundMetric<BoundMeasure> {
+export interface ValueRecorder extends UnboundMetric<BoundValueRecorder> {
   /**
-   * Records the given value to this measure.
+   * Records the given value to this value recorder.
    */
   record(value: number, labels?: Labels): void;
 

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

@@ -20,10 +20,10 @@ import {
   UnboundMetric,
   Labels,
   Counter,
-  Measure,
+  ValueRecorder,
   Observer,
 } from './Metric';
-import { BoundMeasure, BoundCounter } from './BoundInstrument';
+import { BoundValueRecorder, BoundCounter } from './BoundInstrument';
 import { CorrelationContext } from '../correlation_context/CorrelationContext';
 import { SpanContext } from '../trace/span_context';
 import { ObserverResult } from './ObserverResult';
@@ -36,12 +36,12 @@ export class NoopMeter implements Meter {
   constructor() {}
 
   /**
-   * Returns constant noop measure.
+   * Returns constant noop value recorder.
    * @param name the name of the metric.
    * @param [options] the metric options.
    */
-  createMeasure(name: string, options?: MetricOptions): Measure {
-    return NOOP_MEASURE_METRIC;
+  createValueRecorder(name: string, options?: MetricOptions): ValueRecorder {
+    return NOOP_VALUE_RECORDER_METRIC;
   }
 
   /**
@@ -103,8 +103,8 @@ export class NoopCounterMetric extends NoopMetric<BoundCounter>
   }
 }
 
-export class NoopMeasureMetric extends NoopMetric<BoundMeasure>
-  implements Measure {
+export class NoopValueRecorderMetric extends NoopMetric<BoundValueRecorder>
+  implements ValueRecorder {
   record(
     value: number,
     labels: Labels,
@@ -131,7 +131,7 @@ export class NoopBoundCounter implements BoundCounter {
   }
 }
 
-export class NoopBoundMeasure implements BoundMeasure {
+export class NoopBoundValueRecorder implements BoundValueRecorder {
   record(
     value: number,
     correlationContext?: CorrelationContext,
@@ -145,7 +145,9 @@ 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_VALUE_RECORDER = new NoopBoundValueRecorder();
+export const NOOP_VALUE_RECORDER_METRIC = new NoopValueRecorderMetric(
+  NOOP_BOUND_VALUE_RECORDER
+);
 
 export const NOOP_OBSERVER_METRIC = new NoopObserverMetric();

packages/opentelemetry-api/test/noop-implementations/noop-meter.test.ts

@@ -18,9 +18,9 @@ import * as assert from 'assert';
 import {
   NoopMeterProvider,
   NOOP_BOUND_COUNTER,
-  NOOP_BOUND_MEASURE,
+  NOOP_BOUND_VALUE_RECORDER,
   NOOP_COUNTER_METRIC,
-  NOOP_MEASURE_METRIC,
+  NOOP_VALUE_RECORDER_METRIC,
 } from '../../src';
 
 describe('NoopMeter', () => {
@@ -38,20 +38,23 @@ describe('NoopMeter', () => {
     assert.strictEqual(counter.bind(labels), NOOP_BOUND_COUNTER);
     counter.clear();
 
-    const measure = meter.createMeasure('some-name');
-    measure.bind(labels).record(1);
+    const valueRecorder = meter.createValueRecorder('some-name');
+    valueRecorder.bind(labels).record(1);
 
     // ensure the correct noop const is returned
-    assert.strictEqual(measure, NOOP_MEASURE_METRIC);
-    assert.strictEqual(measure.bind(labels), NOOP_BOUND_MEASURE);
+    assert.strictEqual(valueRecorder, NOOP_VALUE_RECORDER_METRIC);
+    assert.strictEqual(valueRecorder.bind(labels), NOOP_BOUND_VALUE_RECORDER);
 
     const options = {
       component: 'tests',
       description: 'the testing package',
     };
 
-    const measureWithOptions = meter.createMeasure('some-name', options);
-    assert.strictEqual(measureWithOptions, NOOP_MEASURE_METRIC);
+    const valueRecorderWithOptions = meter.createValueRecorder(
+      'some-name',
+      options
+    );
+    assert.strictEqual(valueRecorderWithOptions, NOOP_VALUE_RECORDER_METRIC);
     const counterWithOptions = meter.createCounter('some-name', options);
     assert.strictEqual(counterWithOptions, NOOP_COUNTER_METRIC);
   });

packages/opentelemetry-metrics/README.md

@@ -73,8 +73,11 @@ setInterval(()=> {
 
 See [examples/prometheus](https://github.com/open-telemetry/opentelemetry-js/tree/master/examples/prometheus) for a short example.
 
-### Measure
-***Work in progress***
+### Value Recorder
+
+`ValueRecorder` is a non-additive synchronous instrument useful for recording any non-additive number, positive or negative.
+Values captured by `ValueRecorder.record(value)` are treated as individual events belonging to a distribution that is being summarized.
+`ValueRecorder` should be chosen either when capturing measurements that do not contribute meaningfully to a sum, or when capturing numbers that are additive in nature, but where the distribution of individual increments is considered interesting.
 
 ## Useful links
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>

packages/opentelemetry-metrics/src/BoundInstrument.ts

@@ -93,10 +93,10 @@ export class BoundCounter extends BaseBoundInstrument
 }
 
 /**
- * BoundMeasure is an implementation of the {@link BoundMeasure} interface.
+ * BoundValueRecorder is an implementation of the {@link BoundValueRecorder} interface.
  */
-export class BoundMeasure extends BaseBoundInstrument
-  implements api.BoundMeasure {
+export class BoundValueRecorder extends BaseBoundInstrument
+  implements api.BoundValueRecorder {
   private readonly _absolute: boolean;
 
   constructor(
@@ -119,7 +119,7 @@ export class BoundMeasure extends BaseBoundInstrument
   ): void {
     if (this._absolute && value < 0) {
       this._logger.error(
-        `Absolute measure cannot contain negative values for $${Object.values(
+        `Absolute ValueRecorder cannot contain negative values for $${Object.values(
           this._labels
         )}`
       );

packages/opentelemetry-metrics/src/Meter.ts

@@ -18,7 +18,12 @@ import * as api from '@opentelemetry/api';
 import { ConsoleLogger } from '@opentelemetry/core';
 import { Resource } from '@opentelemetry/resources';
 import { BaseBoundInstrument } from './BoundInstrument';
-import { Metric, CounterMetric, MeasureMetric, ObserverMetric } from './Metric';
+import {
+  Metric,
+  CounterMetric,
+  ValueRecorderMetric,
+  ObserverMetric,
+} from './Metric';
 import {
   MetricOptions,
   DEFAULT_METRIC_OPTIONS,
@@ -52,28 +57,36 @@ export class Meter implements api.Meter {
   }
 
   /**
-   * Creates and returns a new {@link Measure}.
+   * Creates and returns a new {@link ValueRecorder}.
    * @param name the name of the metric.
    * @param [options] the metric options.
    */
-  createMeasure(name: string, options?: api.MetricOptions): api.Measure {
+  createValueRecorder(
+    name: string,
+    options?: api.MetricOptions
+  ): api.ValueRecorder {
     if (!this._isValidName(name)) {
       this._logger.warn(
         `Invalid metric name ${name}. Defaulting to noop metric implementation.`
       );
-      return api.NOOP_MEASURE_METRIC;
+      return api.NOOP_VALUE_RECORDER_METRIC;
     }
     const opt: MetricOptions = {
-      absolute: true, // Measures are defined as absolute by default
-      monotonic: false, // not applicable to measure, set to false
+      absolute: true, // value recorders are defined as absolute by default
+      monotonic: false, // not applicable to value recorder, set to false
       logger: this._logger,
       ...DEFAULT_METRIC_OPTIONS,
       ...options,
     };
 
-    const measure = new MeasureMetric(name, opt, this._batcher, this._resource);
-    this._registerMetric(name, measure);
-    return measure;
+    const valueRecorder = new ValueRecorderMetric(
+      name,
+      opt,
+      this._batcher,
+      this._resource
+    );
+    this._registerMetric(name, valueRecorder);
+    return valueRecorder;
   }
 
   /**

packages/opentelemetry-metrics/src/Metric.ts

@@ -19,7 +19,7 @@ import { Resource } from '@opentelemetry/resources';
 import {
   BoundCounter,
   BaseBoundInstrument,
-  BoundMeasure,
+  BoundValueRecorder,
   BoundObserver,
 } from './BoundInstrument';
 import { ObserverResult } from './ObserverResult';
@@ -139,7 +139,8 @@ export class CounterMetric extends Metric<BoundCounter> implements api.Counter {
   }
 }
 
-export class MeasureMetric extends Metric<BoundMeasure> implements api.Measure {
+export class ValueRecorderMetric extends Metric<BoundValueRecorder>
+  implements api.ValueRecorder {
   protected readonly _absolute: boolean;
 
   constructor(
@@ -148,12 +149,12 @@ export class MeasureMetric extends Metric<BoundMeasure> implements api.Measure {
     private readonly _batcher: Batcher,
     resource: Resource
   ) {
-    super(name, options, MetricKind.MEASURE, resource);
+    super(name, options, MetricKind.VALUE_RECORDER, resource);
 
     this._absolute = options.absolute !== undefined ? options.absolute : true; // Absolute default is true
   }
-  protected _makeInstrument(labels: api.Labels): BoundMeasure {
-    return new BoundMeasure(
+  protected _makeInstrument(labels: api.Labels): BoundValueRecorder {
+    return new BoundValueRecorder(
       labels,
       this._disabled,
       this._monotonic,

packages/opentelemetry-metrics/src/export/Batcher.ts

@@ -16,7 +16,7 @@
 
 import {
   CounterSumAggregator,
-  MeasureExactAggregator,
+  ValueRecorderExactAggregator,
   ObserverAggregator,
 } from './aggregators';
 import {
@@ -59,7 +59,7 @@ export class UngroupedBatcher extends Batcher {
       case MetricKind.OBSERVER:
         return new ObserverAggregator();
       default:
-        return new MeasureExactAggregator();
+        return new ValueRecorderExactAggregator();
     }
   }
 

packages/opentelemetry-metrics/src/export/aggregators/measureexact.ts → packages/opentelemetry-metrics/src/export/aggregators/ValueRecorderExact.ts

@@ -20,7 +20,7 @@ import { hrTime } from '@opentelemetry/core';
 import { Distribution } from '../types';
 
 /** Basic aggregator keeping all raw values (events, sum, max and min). */
-export class MeasureExactAggregator implements Aggregator {
+export class ValueRecorderExactAggregator implements Aggregator {
   private _distribution: Distribution;
   private _lastUpdateTime: HrTime = [0, 0];
 

packages/opentelemetry-metrics/src/export/aggregators/index.ts

@@ -16,5 +16,5 @@
 
 export * from './countersum';
 export * from './observer';
-export * from './measureexact';
+export * from './ValueRecorderExact';
 export * from './histogram';

packages/opentelemetry-metrics/src/export/types.ts

@@ -21,7 +21,7 @@ import { Resource } from '@opentelemetry/resources';
 /** The kind of metric. */
 export enum MetricKind {
   COUNTER,
-  MEASURE,
+  VALUE_RECORDER,
   OBSERVER,
 }
 

packages/opentelemetry-metrics/src/types.ts

@@ -43,7 +43,7 @@ export interface MetricOptions {
   /** Monotonic metrics may only increase. */
   monotonic: boolean;
 
-  /** (Measure only) Asserts that this metric will only accept non-negative values. */
+  /** (ValueRecorder only) Asserts that this metric will only accept non-negative values. */
   absolute: boolean;
 
   /** User provided logger. */