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(api-metrics): rename metric instruments to match feature-freeze API specification #2496

Merged
merged 11 commits into from
Oct 15, 2021
2 changes: 1 addition & 1 deletion doc/processor-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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'
});
Expand Down
6 changes: 3 additions & 3 deletions examples/metrics/metrics/observer.js
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ const meter = new MeterProvider({
interval: 2000,
}).getMeter('example-observer');

meter.createValueObserver('cpu_core_usage', {
meter.createObservableGauge('cpu_core_usage', {
description: 'Example of a sync value observer with callback',
legendecas marked this conversation as resolved.
Show resolved Hide resolved
}, async (observerResult) => { // this callback is called once per each interval
await new Promise((resolve) => {
Expand All @@ -34,12 +34,12 @@ meter.createValueObserver('cpu_core_usage', {
});

// no callback as they will be updated in batch observer
const tempMetric = meter.createValueObserver('cpu_temp_per_app', {
const tempMetric = meter.createObservableGauge('cpu_temp_per_app', {
description: 'Example of sync value observer used with async batch observer',
legendecas marked this conversation as resolved.
Show resolved Hide resolved
});

// no callback as they will be updated in batch observer
const cpuUsageMetric = meter.createValueObserver('cpu_usage_per_app', {
const cpuUsageMetric = meter.createObservableGauge('cpu_usage_per_app', {
description: 'Example of sync value observer used with async batch observer',
legendecas marked this conversation as resolved.
Show resolved Hide resolved
});

Expand Down
6 changes: 3 additions & 3 deletions examples/otlp-exporter-node/metrics.js
Original file line number Diff line number Diff line change
Expand Up @@ -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);
105 changes: 53 additions & 52 deletions experimental/packages/opentelemetry-api-metrics/src/NoopMeter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,16 +21,17 @@ import {
UnboundMetric,
Labels,
Counter,
ValueRecorder,
ValueObserver,
Histogram,
ObservableGauge,
UpDownCounter,
BaseObserver,
UpDownSumObserver,
BaseObservable,
ObservableCounter,
ObservableUpDownCounter,
} from './types/Metric';
import {
BoundValueRecorder,
BoundHistogram,
BoundCounter,
BoundBaseObserver,
BoundBaseObservable,
} from './types/BoundInstrument';
import { ObserverResult } from './types/ObserverResult';
import { Observation } from './types/Observation';
Expand All @@ -43,72 +44,72 @@ export class NoopMeter implements Meter {
constructor() {}

/**
* Returns constant noop value recorder.
* Returns a constant noop counter.
* @param name the name of the metric.
* @param [options] the metric options.
*/
createValueRecorder(_name: string, _options?: MetricOptions): ValueRecorder {
legendecas marked this conversation as resolved.
Show resolved Hide resolved
return NOOP_VALUE_RECORDER_METRIC;
createCounter(_name: string, _options?: MetricOptions): Counter {
return NOOP_COUNTER_METRIC;
}

/**
* Returns a constant noop counter.
* Returns a constant noop observable counter.
* @param name the name of the metric.
* @param [options] the metric options.
* @param [callback] the observable counter callback
*/
createCounter(_name: string, _options?: MetricOptions): Counter {
return NOOP_COUNTER_METRIC;
createObservableCounter(
_name: string,
_options?: MetricOptions,
_callback?: (observerResult: ObserverResult) => void
): ObservableCounter {
return NOOP_OBSERVABLE_COUNTER_METRIC;
}

/**
* Returns a constant noop UpDownCounter.
* Returns a constant noop histogram.
* @param name the name of the metric.
* @param [options] the metric options.
*/
createUpDownCounter(_name: string, _options?: MetricOptions): UpDownCounter {
return NOOP_COUNTER_METRIC;
createHistogram(_name: string, _options?: MetricOptions): Histogram {
legendecas marked this conversation as resolved.
Show resolved Hide resolved
return NOOP_HISTOGRAM_METRIC;
}

/**
* 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;
): ObservableGauge {
return NOOP_OBSERVABLE_GAUGE_METRIC;
}

/**
* Returns constant noop sum observer.
* Returns a constant noop UpDownCounter.
* @param name the name of the metric.
* @param [options] the metric options.
* @param [callback] the sum observer callback
*/
createSumObserver(
_name: string,
_options?: MetricOptions,
_callback?: (observerResult: ObserverResult) => void
): ValueObserver {
return NOOP_SUM_OBSERVER_METRIC;
createUpDownCounter(_name: string, _options?: MetricOptions): UpDownCounter {
legendecas marked this conversation as resolved.
Show resolved Hide resolved
return NOOP_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;
): ObservableUpDownCounter {
return NOOP_OBSERVABLE_UP_DOWN_COUNTER_METRIC;
}

/**
Expand Down Expand Up @@ -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 NoopBaseObservableMetric
legendecas marked this conversation as resolved.
Show resolved Hide resolved
extends NoopMetric<BoundBaseObservable>
implements BaseObservable {
observation(): Observation {
return {
observer: this as BaseObserver,
observer: this as BaseObservable,
legendecas marked this conversation as resolved.
Show resolved Hide resolved
value: 0,
};
}
Expand All @@ -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 NoopBoundBaseObservable implements BoundBaseObservable {
legendecas marked this conversation as resolved.
Show resolved Hide resolved
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_BASE_OBSERVABLE = new NoopBoundBaseObservable();
legendecas marked this conversation as resolved.
Show resolved Hide resolved
export const NOOP_OBSERVABLE_GAUGE_METRIC = new NoopBaseObservableMetric(
NOOP_BOUND_BASE_OBSERVABLE
);

export const NOOP_UP_DOWN_SUM_OBSERVER_METRIC = new NoopBaseObserverMetric(
NOOP_BOUND_BASE_OBSERVER
export const NOOP_OBSERVABLE_UP_DOWN_COUNTER_METRIC = new NoopBaseObservableMetric(
NOOP_BOUND_BASE_OBSERVABLE
);

export const NOOP_SUM_OBSERVER_METRIC = new NoopBaseObserverMetric(
NOOP_BOUND_BASE_OBSERVER
export const NOOP_OBSERVABLE_COUNTER_METRIC = new NoopBaseObservableMetric(
NOOP_BOUND_BASE_OBSERVABLE
);

export const NOOP_BATCH_OBSERVER = new NoopBatchObserver();
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Original file line number Diff line number Diff line change
Expand Up @@ -23,16 +23,16 @@ export interface BoundCounter {
add(value: number): void;
}

/** ValueRecorder to report instantaneous measurement of a value. */
export interface BoundValueRecorder {
/** Histogram to report instantaneous measurement of a value. */
export interface BoundHistogram {
/**
* Records the given value to this value recorder.
* Records the given value to this histogram.
* @param value to record.
*/
record(value: number): void;
}

/** An Instrument for Base Observer */
export interface BoundBaseObserver {
/** An Instrument for Base Observable */
export interface BoundBaseObservable {
update(value: number): void;
}
Original file line number Diff line number Diff line change
Expand Up @@ -18,38 +18,62 @@ import { BatchObserverResult } from './BatchObserverResult';
import {
MetricOptions,
Counter,
ValueRecorder,
ValueObserver,
Histogram,
ObservableGauge,
BatchObserverOptions,
UpDownCounter,
SumObserver,
UpDownSumObserver,
ObservableCounter,
ObservableUpDownCounter,
} from './Metric';
import { ObserverResult } from './ObserverResult';

/**
* An interface to allow the recording metrics.
*
* {@link Metric}s are used for recording pre-defined aggregation (`Counter`),
* or raw values (`ValueRecorder`) in which the aggregation and labels
* or raw values (`Histogram`) in which the aggregation and labels
* for the exported metric are deferred.
*/
export interface Meter {
/**
* Creates and returns a new `ValueRecorder`.
* Creates a new `Counter` metric. Generally, this kind of metric when the
legendecas marked this conversation as resolved.
Show resolved Hide resolved
* value is a quantity, the sum is of primary interest, and the event count
* and value distribution are not of primary interest.
* @param name the name of the metric.
* @param [options] the metric options.
*/
createValueRecorder(name: string, options?: MetricOptions): ValueRecorder;
createCounter(name: string, options?: MetricOptions): Counter;
legendecas marked this conversation as resolved.
Show resolved Hide resolved

/**
* Creates a new `Counter` metric. Generally, this kind of metric when the
* value is a quantity, the sum is of primary interest, and the event count
* and value distribution are not of primary interest.
* Creates a new `ObservableCounter` metric.
* @param name the name of the metric.
* @param [options] the metric options.
* @param [callback] the observable callback
*/
createCounter(name: string, options?: MetricOptions): Counter;
legendecas marked this conversation as resolved.
Show resolved Hide resolved
createObservableCounter(
name: string,
options?: MetricOptions,
callback?: (observerResult: ObserverResult) => void
): ObservableCounter;

/**
* Creates and returns a new `Histogram`.
* @param name the name of the metric.
* @param [options] the metric options.
*/
createHistogram(name: string, options?: MetricOptions): Histogram;

/**
* Creates a new `ObservableGauge` metric.
* @param name the name of the metric.
* @param [options] the metric options.
* @param [callback] the observable callback
*/
createObservableGauge(
name: string,
options?: MetricOptions,
callback?: (observerResult: ObserverResult) => void
): ObservableGauge;

/**
* Creates a new `UpDownCounter` metric. UpDownCounter is a synchronous
Expand All @@ -71,40 +95,16 @@ export interface Meter {
createUpDownCounter(name: string, options?: MetricOptions): UpDownCounter;

/**
* Creates a new `ValueObserver` metric.
* @param name the name of the metric.
* @param [options] the metric options.
* @param [callback] the observer callback
*/
createValueObserver(
name: string,
options?: MetricOptions,
callback?: (observerResult: ObserverResult) => void
): ValueObserver;

/**
* Creates a new `SumObserver` metric.
* @param name the name of the metric.
* @param [options] the metric options.
* @param [callback] the observer callback
*/
createSumObserver(
name: string,
options?: MetricOptions,
callback?: (observerResult: ObserverResult) => void
): SumObserver;

/**
* Creates a new `UpDownSumObserver` metric.
* Creates a new `ObservableUpDownCounter` metric.
* @param name the name of the metric.
* @param [options] the metric options.
* @param [callback] the observer callback
* @param [callback] the observable callback
*/
createUpDownSumObserver(
createObservableUpDownCounter(
name: string,
options?: MetricOptions,
callback?: (observerResult: ObserverResult) => void
): UpDownSumObserver;
): ObservableUpDownCounter;

/**
* Creates a new `BatchObserver`, can be used to update many metrics
Expand Down
Loading