diff --git a/experimental/examples/prometheus/index.js b/experimental/examples/prometheus/index.js index 17da9c3b003..3394e404817 100644 --- a/experimental/examples/prometheus/index.js +++ b/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); diff --git a/experimental/packages/opentelemetry-sdk-metrics-base/README.md b/experimental/packages/opentelemetry-sdk-metrics-base/README.md index dcd6f586f29..c5ebc65cdeb 100644 --- a/experimental/packages/opentelemetry-sdk-metrics-base/README.md +++ b/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: diff --git a/experimental/packages/opentelemetry-sdk-metrics-base/src/InstrumentDescriptor.ts b/experimental/packages/opentelemetry-sdk-metrics-base/src/InstrumentDescriptor.ts index fa2985ff9d1..e511cd8dd33 100644 --- a/experimental/packages/opentelemetry-sdk-metrics-base/src/InstrumentDescriptor.ts +++ b/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; diff --git a/experimental/packages/opentelemetry-sdk-metrics-base/src/MeterProvider.ts b/experimental/packages/opentelemetry-sdk-metrics-base/src/MeterProvider.ts index 5c0e2b6e1dc..41abed5e4d7 100644 --- a/experimental/packages/opentelemetry-sdk-metrics-base/src/MeterProvider.ts +++ b/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. diff --git a/experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricData.ts b/experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricData.ts index 351dbaa76c3..74efb965311 100644 --- a/experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricData.ts +++ b/experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricData.ts @@ -66,8 +66,20 @@ 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[]; } @@ -75,8 +87,22 @@ export interface CollectionResult { * 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 { */ 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; } diff --git a/experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricExporter.ts b/experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricExporter.ts index 2460a495cae..217068ae9c6 100644 --- a/experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricExporter.ts +++ b/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; + /** + * 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; - } export class ConsoleMetricExporter implements PushMetricExporter { diff --git a/experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricProducer.ts b/experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricProducer.ts index 827e32c7b90..87af8a1210d 100644 --- a/experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricProducer.ts +++ b/experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricProducer.ts @@ -17,6 +17,14 @@ 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; } @@ -24,5 +32,9 @@ export interface MetricCollectOptions { * 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; } diff --git a/experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricReader.ts b/experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricReader.ts index 20d06c850b9..35d86c5d943 100644 --- a/experimental/packages/opentelemetry-sdk-metrics-base/src/export/MetricReader.ts +++ b/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; diff --git a/experimental/packages/opentelemetry-sdk-metrics-base/src/export/PeriodicExportingMetricReader.ts b/experimental/packages/opentelemetry-sdk-metrics-base/src/export/PeriodicExportingMetricReader.ts index 68db6902b02..ababba83733 100644 --- a/experimental/packages/opentelemetry-sdk-metrics-base/src/export/PeriodicExportingMetricReader.ts +++ b/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); }