docs(sdk-metrics): update document on public interfaces (#3075)

Co-authored-by: Valentin Marchaud <thisismac47@gmail.com>

experimental/examples/prometheus/index.js

@@ -31,8 +31,17 @@ const upDownCounter = meter.createUpDownCounter('test_up_down_counter', {
 
 const attributes = { pid: process.pid, environment: 'staging' };
 
+let counter = 0;
+const observableCounter = meter.createObservableCounter('observable_requests', {
+  description: 'Example of an ObservableCounter',
+});
+observableCounter.addCallback(observableResult => {
+  observableResult.observe(counter, attributes);
+});
+
 // Record metrics
 setInterval(() => {
+  counter++;
   requestCounter.add(1, attributes);
   upDownCounter.add(Math.random() > 0.5 ? 1 : -1, attributes);
 }, 1000);

experimental/packages/opentelemetry-sdk-metrics-base/README.md

@@ -3,31 +3,20 @@
 [![NPM Published Version][npm-img]][npm-url]
 [![Apache License][license-image]][license-image]
 
-OpenTelemetry metrics allow a user to collect data and export it to a metrics backend like [Prometheus](https://prometheus.io/).
+OpenTelemetry metrics module contains the foundation for all metrics SDKs of [opentelemetry-js](https://github.com/open-telemetry/opentelemetry-js).
 
-## Work In Progress
+Used standalone, this module provides methods for manual instrumentation of code, offering full control over recording metrics for client-side JavaScript (browser) and Node.js.
 
-The OpenTelemetry SDK in this directory is undergoing drastic changes. If you need to use metrics, we recommend you use [version `0.27.0`](https://github.com/open-telemetry/opentelemetry-js/tree/experimental/v0.27.0/experimental/packages/opentelemetry-sdk-metrics-base).
+It does **not** provide automated instrumentation of known libraries or host environment metrics out-of-the-box.
 
 ## Installation
 
 ```bash
-npm install --save "@opentelemetry/sdk-metrics-base@~0.27.0"
-```
-
-## Usage
-
-Please see the [version `0.27.0` README](https://github.com/open-telemetry/opentelemetry-js/tree/experimental/v0.27.0/experimental/packages/opentelemetry-sdk-metrics-base#usage).
-
-TODO: Add usage information for updated SDK
-
-## Installation of the Latest experimental version
-
-```bash
+npm install --save @opentelemetry/api-metrics
 npm install --save @opentelemetry/sdk-metrics-base
 ```
 
-## Usage of the Latest experimental version
+## Usage
 
 The basic setup of the SDK can be seen as followings:
 
@@ -66,12 +55,13 @@ opentelemetry.getMeter('default')
 async function batchObservableCallback(batchObservableResult) {
   // ... do async stuff
   batchObservableResult.observe(observableCounter, 1, { attributeKey: 'attribute-value' });
-
-  // This is been dropped since the observable is not associated with the callback at registration.
-  batchObservableResult.observe(otherObservable, 2);
 }
 ```
 
+## Example
+
+See [examples/prometheus](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/examples/prometheus) for an end-to-end example, including exporting metrics.
+
 ## Useful links
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>

experimental/packages/opentelemetry-sdk-metrics-base/src/InstrumentDescriptor.ts

@@ -29,6 +29,9 @@ export enum InstrumentType {
   OBSERVABLE_UP_DOWN_COUNTER = 'OBSERVABLE_UP_DOWN_COUNTER',
 }
 
+/**
+ * An interface describing the instrument.
+ */
 export interface InstrumentDescriptor {
   readonly name: string;
   readonly description: string;

experimental/packages/opentelemetry-sdk-metrics-base/src/MeterProvider.ts

@@ -60,6 +60,9 @@ export type ViewOptions = {
 };
 
 export type SelectorOptions = {
+  /**
+   * Selects instrument by their fields.
+   */
   instrument?: {
     /**
      * The type of the Instrument(s).
@@ -70,6 +73,9 @@ export type SelectorOptions = {
      */
     name?: string,
   }
+  /**
+   * Selects instrument by fields of their meter.
+   */
   meter?: {
     /**
      * The name of the Meter.

experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricData.ts

@@ -66,17 +66,43 @@ export interface ResourceMetrics {
   scopeMetrics: ScopeMetrics[];
 }
 
+/**
+ * Represents the collection result of the metrics. If there are any
+ * non-critical errors in the collection, like throwing in a single observable
+ * callback, these errors are aggregated in the {@link CollectionResult.errors}
+ * array and other successfully collected metrics are returned.
+ */
 export interface CollectionResult {
+  /**
+   * Collected metrics.
+   */
   resourceMetrics: ResourceMetrics;
+  /**
+   * Arbitrary JavaScript exception values.
+   */
   errors: unknown[];
 }
 
 /**
  * The aggregated point data type.
  */
 export enum DataPointType {
+  /**
+   * A singular metric data point has only a single numeric value.
+   */
   SINGULAR,
+  /**
+   * A histogram data point contains a histogram statistics of collected
+   * values with a list of explicit bucket boundaries and statistics such
+   * as min, max, count, and sum of all collected values.
+   */
   HISTOGRAM,
+  /**
+   * An exponential histogram data point contains a histogram statistics of
+   * collected values where bucket boundaries are automatically calculated
+   * using an exponential function, and statistics such as min, max, count,
+   * and sum of all collected values.
+   */
   EXPONENTIAL_HISTOGRAM,
 }
 
@@ -101,7 +127,8 @@ export interface DataPoint<T> {
    */
   readonly attributes: MetricAttributes;
   /**
-   * The value for this DataPoint.
+   * The value for this DataPoint. The type of the value is indicated by the
+   * {@link DataPointType}.
    */
   readonly value: T;
 }

experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricExporter.ts

@@ -22,19 +22,37 @@ import {
 } from '@opentelemetry/core';
 import { InstrumentType } from '../InstrumentDescriptor';
 
-
-// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#metricexporter
-
+/**
+ * An interface that allows different metric services to export recorded data
+ * in their own format.
+ *
+ * To export data this MUST be registered to the Metrics SDK with a MetricReader.
+ */
 export interface PushMetricExporter {
-
+  /**
+   * Called to export sampled {@link ResourceMetrics}.
+   * @param metrics the metric data to be exported.
+   */
   export(metrics: ResourceMetrics, resultCallback: (result: ExportResult) => void): void;
 
+  /**
+   * Ensure that the export of any metrics the exporter has received is
+   * completed before the returned promise is settled.
+   */
   forceFlush(): Promise<void>;
 
+  /**
+   * Select the {@link AggregationTemporality} for the given
+   * {@link InstrumentType} for this exporter.
+   */
   selectAggregationTemporality(instrumentType: InstrumentType): AggregationTemporality;
 
+  /**
+   * Returns a promise which resolves when the last exportation is completed.
+   * Further calls to {@link PushMetricExporter.export} may not export the
+   * data.
+   */
   shutdown(): Promise<void>;
-
 }
 
 export class ConsoleMetricExporter implements PushMetricExporter {

experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricProducer.ts

@@ -17,12 +17,24 @@
 import { CollectionResult } from './MetricData';
 
 export interface MetricCollectOptions {
+  /**
+   * Timeout for the SDK to perform the involved asynchronous callback
+   * functions.
+   *
+   * If the callback functions failed to finish the observation in time,
+   * their results are discarded and an error is appended in the
+   * {@link CollectionResult.errors}.
+   */
   timeoutMillis?: number;
 }
 
 /**
  * This is a public interface that represent an export state of a MetricReader.
  */
 export interface MetricProducer {
+  /**
+   * Collects the metrics from the SDK. If there are asynchronous Instruments
+   * involved, their callback functions will be triggered.
+   */
   collect(options?: MetricCollectOptions): Promise<CollectionResult>;
 }

experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricReader.ts

@@ -22,8 +22,6 @@ import { callWithTimeout } from '../utils';
 import { InstrumentType } from '../InstrumentDescriptor';
 import { CollectionOptions, ForceFlushOptions, ShutdownOptions } from '../types';
 
-// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#metricreader
-
 /**
  * A registered reader of metrics that, when linked to a {@link MetricProducer}, offers global
  * control over metrics.
@@ -49,7 +47,8 @@ export abstract class MetricReader {
   }
 
   /**
-   * Get the default {@link AggregationTemporality} for the given {@link InstrumentType}
+   * Select the {@link AggregationTemporality} for the given
+   * {@link InstrumentType} for this reader.
    */
   abstract selectAggregationTemporality(instrumentType: InstrumentType): AggregationTemporality;
 

experimental/packages/opentelemetry-sdk-metrics-base/src/export/PeriodicExportingMetricReader.ts

@@ -114,6 +114,9 @@ export class PeriodicExportingMetricReader extends MetricReader {
     await this._exporter.shutdown();
   }
 
+  /**
+   * @inheritdoc
+   */
   selectAggregationTemporality(instrumentType: InstrumentType): AggregationTemporality {
     return this._exporter.selectAggregationTemporality(instrumentType);
   }