Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 5 commits into from
Jan 26, 2022
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,20 @@
*/

import { MetricOptions, ValueType } from '@opentelemetry/api-metrics-wip';
import { InstrumentType } from './Instruments';
import { View } from './view/View';

/**
* Supported types of metric instruments.
* @see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe better to point to a tag/commit instead main which moves day by day.
applies also to other places.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, like said, the spec is being updated day by day and it has not been released with a "tagged" version yet. I'd remove these links for now.

*/
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;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) { }

Expand All @@ -42,13 +31,27 @@ export class SyncInstrument {
}
}

export class UpDownCounter extends SyncInstrument implements metrics.Counter {
/**
* The class implements {@link metrics.UpDownCounter} interface.
* @see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#updowncounter
*/
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.
* @see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#counter
*/
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}`);
Expand All @@ -59,7 +62,14 @@ export class Counter extends SyncInstrument implements metrics.Counter {
}
}

/**
* The class implements {@link metrics.Histogram} interface.
* @see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#histogram
*/
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);
}
Expand Down
41 changes: 30 additions & 11 deletions experimental/packages/opentelemetry-sdk-metrics-base/src/Meter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -28,40 +28,47 @@ 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.
* @see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#meter
*/
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,
Expand All @@ -71,6 +78,9 @@ export class Meter implements metrics.Meter {
this._registerAsyncMetricStorage(descriptor, callback);
}

/**
* Create a ObservableCounter instrument.
*/
createObservableCounter(
name: string,
callback: metrics.ObservableCallback,
Expand All @@ -80,6 +90,9 @@ export class Meter implements metrics.Meter {
this._registerAsyncMetricStorage(descriptor, callback);
}

/**
* Create a ObservableUpDownCounter instrument.
*/
createObservableUpDownCounter(
name: string,
callback: metrics.ObservableCallback,
Expand Down Expand Up @@ -112,6 +125,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(
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,20 +25,29 @@ 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.
* @see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#meterprovider
*/
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) {
Expand All @@ -49,6 +58,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);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
/**
* AggregationTemporality indicates the way additive quantities are expressed.
*
* https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/datamodel.md#temporality
* @see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/datamodel.md#temporality
*/
export enum AggregationTemporality {
DELTA,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
legendecas marked this conversation as resolved.
Show resolved Hide resolved
*/
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
legendecas marked this conversation as resolved.
Show resolved Hide resolved
*/
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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Loading