feat(sdk-metrics-base): document and export basic APIs (#2725)

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

@@ -15,9 +15,19 @@
  */
 
 import { MetricOptions, ValueType } from '@opentelemetry/api-metrics-wip';
-import { InstrumentType } from './Instruments';
 import { View } from './view/View';
 
+/**
+ * Supported types of metric instruments.
+ */
+ export enum InstrumentType {
+  COUNTER = 'COUNTER',
+  HISTOGRAM = 'HISTOGRAM',
+  UP_DOWN_COUNTER = 'UP_DOWN_COUNTER',
+  OBSERVABLE_COUNTER = 'OBSERVABLE_COUNTER',
+  OBSERVABLE_GAUGE = 'OBSERVABLE_GAUGE',
+  OBSERVABLE_UP_DOWN_COUNTER = 'OBSERVABLE_UP_DOWN_COUNTER',
+}
 
 export interface InstrumentDescriptor {
   readonly name: string;

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

@@ -19,17 +19,6 @@ import * as metrics from '@opentelemetry/api-metrics-wip';
 import { InstrumentDescriptor } from './InstrumentDescriptor';
 import { WritableMetricStorage } from './state/WritableMetricStorage';
 
-// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument
-
-export enum InstrumentType {
-  COUNTER = 'COUNTER',
-  HISTOGRAM = 'HISTOGRAM',
-  UP_DOWN_COUNTER = 'UP_DOWN_COUNTER',
-  OBSERVABLE_COUNTER = 'OBSERVABLE_COUNTER',
-  OBSERVABLE_GAUGE = 'OBSERVABLE_GAUGE',
-  OBSERVABLE_UP_DOWN_COUNTER = 'OBSERVABLE_UP_DOWN_COUNTER',
-}
-
 export class SyncInstrument {
   constructor(private _writableMetricStorage: WritableMetricStorage, private _descriptor: InstrumentDescriptor) { }
 
@@ -42,13 +31,25 @@ export class SyncInstrument {
   }
 }
 
-export class UpDownCounter extends SyncInstrument implements metrics.Counter {
+/**
+ * The class implements {@link metrics.UpDownCounter} interface.
+ */
+export class UpDownCounter extends SyncInstrument implements metrics.UpDownCounter {
+  /**
+   * Increment value of counter by the input. Inputs may be negative.
+   */
   add(value: number, attributes?: metrics.Attributes, ctx?: api.Context): void {
     this.aggregate(value, attributes, ctx);
   }
 }
 
+/**
+ * The class implements {@link metrics.Counter} interface.
+ */
 export class Counter extends SyncInstrument implements metrics.Counter {
+  /**
+   * Increment value of counter by the input. Inputs may not be negative.
+   */
   add(value: number, attributes?: metrics.Attributes, ctx?: api.Context): void {
     if (value < 0) {
       api.diag.warn(`negative value provided to counter ${this.getName()}: ${value}`);
@@ -59,7 +60,13 @@ export class Counter extends SyncInstrument implements metrics.Counter {
   }
 }
 
+/**
+ * The class implements {@link metrics.Histogram} interface.
+ */
 export class Histogram extends SyncInstrument implements metrics.Histogram {
+  /**
+   * Records a measurement. Value of the measurement must not be negative.
+   */
   record(value: number, attributes?: metrics.Attributes, ctx?: api.Context): void {
     this.aggregate(value, attributes, ctx);
   }

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

@@ -16,8 +16,8 @@
 
 import * as metrics from '@opentelemetry/api-metrics-wip';
 import { InstrumentationLibrary } from '@opentelemetry/core';
-import { createInstrumentDescriptor, InstrumentDescriptor } from './InstrumentDescriptor';
-import { Counter, Histogram, InstrumentType, UpDownCounter } from './Instruments';
+import { createInstrumentDescriptor, InstrumentDescriptor, InstrumentType } from './InstrumentDescriptor';
+import { Counter, Histogram, UpDownCounter } from './Instruments';
 import { MeterProviderSharedState } from './state/MeterProviderSharedState';
 import { MultiMetricStorage } from './state/MultiWritableMetricStorage';
 import { SyncMetricStorage } from './state/SyncMetricStorage';
@@ -28,40 +28,46 @@ import { MetricCollectorHandle } from './state/MetricCollector';
 import { HrTime } from '@opentelemetry/api';
 import { AsyncMetricStorage } from './state/AsyncMetricStorage';
 
-// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#meter
-
+/**
+ * This class implements the {@link metrics.Meter} interface.
+ */
 export class Meter implements metrics.Meter {
   private _metricStorageRegistry = new Map<string, MetricStorage>();
 
-  // instrumentation library required by spec to be on meter
-  // spec requires provider config changes to apply to previously created meters, achieved by holding a reference to the provider
   constructor(private _meterProviderSharedState: MeterProviderSharedState, private _instrumentationLibrary: InstrumentationLibrary) {
     this._meterProviderSharedState.meters.push(this);
   }
 
-  /** this exists just to prevent ts errors from unused variables and may be removed */
-  getInstrumentationLibrary(): InstrumentationLibrary {
-    return this._instrumentationLibrary;
-  }
-
+  /**
+   * Create a {@link metrics.Histogram} instrument.
+   */
   createHistogram(name: string, options?: metrics.HistogramOptions): metrics.Histogram {
     const descriptor = createInstrumentDescriptor(name, InstrumentType.HISTOGRAM, options);
     const storage = this._registerMetricStorage(descriptor);
     return new Histogram(storage, descriptor);
   }
 
+  /**
+   * Create a {@link metrics.Counter} instrument.
+   */
   createCounter(name: string, options?: metrics.CounterOptions): metrics.Counter {
     const descriptor = createInstrumentDescriptor(name, InstrumentType.COUNTER, options);
     const storage = this._registerMetricStorage(descriptor);
     return new Counter(storage, descriptor);
   }
 
+  /**
+   * Create a {@link metrics.UpDownCounter} instrument.
+   */
   createUpDownCounter(name: string, options?: metrics.UpDownCounterOptions): metrics.UpDownCounter {
     const descriptor = createInstrumentDescriptor(name, InstrumentType.UP_DOWN_COUNTER, options);
     const storage = this._registerMetricStorage(descriptor);
     return new UpDownCounter(storage, descriptor);
   }
 
+  /**
+   * Create a ObservableGauge instrument.
+   */
   createObservableGauge(
     name: string,
     callback: metrics.ObservableCallback,
@@ -71,6 +77,9 @@ export class Meter implements metrics.Meter {
     this._registerAsyncMetricStorage(descriptor, callback);
   }
 
+  /**
+   * Create a ObservableCounter instrument.
+   */
   createObservableCounter(
     name: string,
     callback: metrics.ObservableCallback,
@@ -80,6 +89,9 @@ export class Meter implements metrics.Meter {
     this._registerAsyncMetricStorage(descriptor, callback);
   }
 
+  /**
+   * Create a ObservableUpDownCounter instrument.
+   */
   createObservableUpDownCounter(
     name: string,
     callback: metrics.ObservableCallback,
@@ -112,6 +124,12 @@ export class Meter implements metrics.Meter {
     });
   }
 
+  /**
+   * @internal
+   * @param collector opaque handle of {@link MetricCollector} which initiated the collection.
+   * @param collectionTime the HrTime at which the collection was initiated.
+   * @returns the list of {@link MetricData} collected.
+   */
   async collect(collector: MetricCollectorHandle, collectionTime: HrTime): Promise<MetricData[]> {
     const result = await Promise.all(Array.from(this._metricStorageRegistry.values()).map(metricStorage => {
       return metricStorage.collect(

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

@@ -25,20 +25,28 @@ import { MeterSelector } from './view/MeterSelector';
 import { View } from './view/View';
 import { MetricCollector } from './state/MetricCollector';
 
-// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#meterprovider
-
-export type MeterProviderOptions = {
+/**
+ * MeterProviderOptions provides an interface for configuring a MeterProvider.
+ */
+export interface MeterProviderOptions {
+  /** Resource associated with metric telemetry  */
   resource?: Resource;
-};
+}
 
-export class MeterProvider {
+/**
+ * This class implements the {@link metrics.MeterProvider} interface.
+ */
+export class MeterProvider implements metrics.MeterProvider {
   private _sharedState: MeterProviderSharedState;
   private _shutdown = false;
 
   constructor(options?: MeterProviderOptions) {
     this._sharedState = new MeterProviderSharedState(options?.resource ?? Resource.empty());
   }
 
+  /**
+   * Get a meter with the configuration of the MeterProvider.
+   */
   getMeter(name: string, version = '', options: metrics.MeterOptions = {}): metrics.Meter {
     // https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#meter-creation
     if (this._shutdown) {
@@ -49,6 +57,12 @@ export class MeterProvider {
     return new Meter(this._sharedState, { name, version, schemaUrl: options.schemaUrl });
   }
 
+  /**
+   * Register a {@link MetricReader} to the meter provider. After the
+   * registration, the MetricReader can start metrics collection.
+   *
+   * @param metricReader the metric reader to be registered.
+   */
   addMetricReader(metricReader: MetricReader) {
     const collector = new MetricCollector(this._sharedState, metricReader);
     metricReader.setMetricProducer(collector);

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

@@ -17,9 +17,18 @@
 import * as metrics from '@opentelemetry/api-metrics-wip';
 import { AttributeHashMap } from './state/HashMap';
 
+/**
+ * The class implements {@link metrics.observableResult} interface.
+ */
 export class ObservableResult implements metrics.ObservableResult {
+  /**
+   * @internal
+   */
   buffer = new AttributeHashMap<number>();
 
+  /**
+   * Observe a measurement of the value associated with the given attributes.
+   */
   observe(value: number, attributes: metrics.Attributes = {}): void {
     this.buffer.set(attributes, value);
   }

experimental/packages/opentelemetry-sdk-metrics-base/src/exemplar/AlignedHistogramBucketExemplarReservoir.ts

@@ -22,9 +22,8 @@ import { FixedSizeExemplarReservoirBase } from './ExemplarReservoir';
 
 /**
  * AlignedHistogramBucketExemplarReservoir takes the same boundaries
- * configuration of a Histogram. This alogorithm keeps the last seen measurement
+ * configuration of a Histogram. This algorithm keeps the last seen measurement
  * that falls within a histogram bucket.
- * https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#exemplar-defaults
  */
 export class AlignedHistogramBucketExemplarReservoir extends FixedSizeExemplarReservoirBase {
   private _boundaries: number[];

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

@@ -16,8 +16,6 @@
 
 /**
  * AggregationTemporality indicates the way additive quantities are expressed.
- *
- * https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/datamodel.md#temporality
  */
 export enum AggregationTemporality {
   DELTA,

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

@@ -21,31 +21,63 @@ import { Resource } from '@opentelemetry/resources';
 import { InstrumentDescriptor } from '../InstrumentDescriptor';
 import { Histogram } from '../aggregator/types';
 
+/**
+ * Basic metric data fields.
+ */
 export interface BaseMetricData {
+  /**
+   * Resource associated with metric telemetry.
+   */
   readonly resource: Resource;
+  /**
+   * InstrumentationLibrary which created the metric instrument.
+   */
   readonly instrumentationLibrary: InstrumentationLibrary;
+  /**
+   * InstrumentDescriptor which describes the metric instrument.
+   */
   readonly instrumentDescriptor: InstrumentDescriptor;
+  /**
+   * PointDataType of the metric instrument.
+   */
   readonly pointDataType: PointDataType,
 }
 
+/**
+ * Represents a metric data aggregated by either a LastValueAggregation or
+ * SumAggregation.
+ */
 export interface SingularMetricData extends BaseMetricData {
   readonly pointDataType: PointDataType.SINGULAR,
   readonly pointData: PointData<number>[],
 }
 
+/**
+ * Represents a metric data aggregated by a HistogramAggregation.
+ */
 export interface HistogramMetricData extends BaseMetricData {
   readonly pointDataType: PointDataType.HISTOGRAM,
   readonly pointData: PointData<Histogram>[],
 }
 
+/**
+ * Represents an aggregated metric data.
+ */
 export type MetricData = SingularMetricData | HistogramMetricData;
 
+/**
+ * The aggregated point data type.
+ */
 export enum PointDataType {
   SINGULAR,
   HISTOGRAM,
   EXPONENTIAL_HISTOGRAM,
 }
 
+/**
+ * Represents an aggregated point data with start time, end time and their
+ * associated attributes and points.
+ */
 export interface PointData<T> {
   /**
    * The start epoch timestamp of the PointData, usually the time when

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

@@ -14,6 +14,15 @@
  * limitations under the License.
  */
 
-export { MeterProvider, MeterProviderOptions } from './MeterProvider';
+export * from './export/AggregationTemporality';
+export * from './export/MetricData';
 export * from './export/MetricExporter';
+export * from './export/MetricProducer';
 export * from './export/MetricReader';
+export * from './export/PeriodicExportingMetricReader';
+export { InstrumentDescriptor, InstrumentType } from './InstrumentDescriptor';
+export * from './Instruments';
+export * from './Meter';
+export * from './MeterProvider';
+export * from './ObservableResult';
+export { TimeoutError } from './utils';