Merge branch 'main' into metrics-ff/schema-url

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,8 +15,29 @@ Before creating a pull request, please make sure:
 
 ## Which problem is this PR solving?
 
--
+Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.
+
+Fixes # (issue)
 
 ## Short description of the changes
 
--
+## Type of change
+
+Please delete options that are not relevant.
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] This change requires a documentation update
+
+## How Has This Been Tested?
+
+Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration
+
+- [ ] Test A
+
+## Checklist:
+
+- [ ] Followed the style guidelines of this project
+- [ ] Unit tests have been added
+- [ ] Documentation has been updated

.github/workflows/peer-api.yaml

@@ -18,6 +18,9 @@ jobs:
       - name: Install lerna
         run: npm install -g lerna
 
+      - name: Install semver 
+        run: npm install semver
+
       - name: Check API dependency semantics (stable)
         run: lerna exec --ignore propagation-validation-server "node ../../scripts/peer-api-check.js"
 

README.md

@@ -2,7 +2,7 @@
 ---
 <p align="center">
   <strong>
-    <a href="https://github.com/open-telemetry/opentelemetry-js/blob/main/getting-started/README.md">Getting Started</a>
+    <a href="https://opentelemetry.io/docs/js/getting_started/">Getting Started</a>
     &nbsp;&nbsp;&bull;&nbsp;&nbsp;
     <a href="https://open-telemetry.github.io/opentelemetry-js-api">API Reference</a>
     &nbsp;&nbsp;&bull;&nbsp;&nbsp;
@@ -49,7 +49,7 @@ This is the JavaScript version of [OpenTelemetry](https://opentelemetry.io/), a
 
 | API Version | Core version | Experimental Packages | Contrib Version         |
 | ----------- |--------------| --------------------- |-------------------------|
-| 1.0.x       | 1.x          | 0.26.x                | ------                  |
+| 1.0.x       | 1.x          | 0.26.x                | 0.26.x                  |
 | 1.0.x       | 0.26.x       | -----                 | ------                  |
 | 1.0.x       | 0.25.x       | -----                 | ------                  |
 | 1.0.x       | 0.24.x       | -----                 | 0.24.x                  |
@@ -131,7 +131,7 @@ process.on('SIGTERM', () => {
 node -r ./tracing.js app.js
 ```
 
-The above example will emit auto-instrumented telemetry about your Node.js application to the console. For a more in-depth example, see the [Getting Started Guide](https://github.com/open-telemetry/opentelemetry-js/blob/main/getting-started/README.md). For more information about automatic instrumentation see [@opentelemetry/sdk-trace-node][otel-node], which provides auto-instrumentation for Node.js applications. If the automatic instrumentation does not suit your needs, or you would like to create manual traces, see [@opentelemetry/sdk-trace-base][otel-tracing]
+The above example will emit auto-instrumented telemetry about your Node.js application to the console. For a more in-depth example, see the [Getting Started Guide](https://opentelemetry.io/docs/js/getting_started/). For more information about automatic instrumentation see [@opentelemetry/sdk-trace-node][otel-node], which provides auto-instrumentation for Node.js applications. If the automatic instrumentation does not suit your needs, or you would like to create manual traces, see [@opentelemetry/sdk-trace-base][otel-tracing]
 
 ### Library Author
 
@@ -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/package.json

@@ -54,11 +54,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "peerDependencies": {
-    "@opentelemetry/api": "^1.0.2"
-  },
   "devDependencies": {
-    "@opentelemetry/api": "^1.0.2",
     "@types/mocha": "8.2.3",
     "@types/node": "14.17.11",
     "@types/webpack-env": "1.16.2",

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 */