Skip to content

Commit

Permalink
chore: rename Metric Handle to Bound Instrument (open-telemetry#634)
Browse files Browse the repository at this point in the history
  • Loading branch information
cthulhu-bot committed Dec 20, 2019
1 parent 3593a69 commit 9e8d389
Show file tree
Hide file tree
Showing 19 changed files with 310 additions and 283 deletions.
8 changes: 4 additions & 4 deletions examples/prometheus/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -46,10 +46,10 @@ setInterval(() => {

currentMonotonicGaugeValue += Math.random();

monotonicCounter.getHandle(labels).add(1);
nonMonotonicCounter.getHandle(labels).add(Math.random() > 0.5 ? 1 : -1);
monotonicGauge.getHandle(labels).set(currentMonotonicGaugeValue);
monotonicCounter.bind(labels).add(1);
nonMonotonicCounter.bind(labels).add(Math.random() > 0.5 ? 1 : -1);
monotonicGauge.bind(labels).set(currentMonotonicGaugeValue);
nonMonotonicGauge
.getHandle(labels)
.bind(labels)
.set(Math.random() > 0.5 ? Math.random() * 10 : -Math.random() * 10);
}, 1000);
22 changes: 11 additions & 11 deletions getting-started/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -227,17 +227,17 @@ const requestCount = meter.createCounter("requests", {
description: "Count all incoming requests"
});
const handles = new Map();
const instruments = new Map();
module.exports.countAllRequests = () => {
return (req, res, next) => {
if (!handles.has(req.path)) {
if (!instruments.has(req.path)) {
const labelSet = meter.labels({ route: req.path });
const handle = requestCount.getHandle(labelSet);
handles.set(req.path, handle);
const instrument = requestCount.bind(labelSet);
instruments.set(req.path, instrument);
}
handles.get(req.path).add(1);
instruments.get(req.path).add(1);
next();
};
};
Expand All @@ -253,7 +253,7 @@ app.use(countAllRequests());

Now, when we make requests to our service our meter will count all requests.

**Note**: Creating a new `labelSet` and `handle` on every request is not ideal as creating the `labelSet` can often be an expensive operation. This is why handles are created and stored in a `Map` according to the route key.
**Note**: Creating a new `labelSet` and `instrument` on every request is not ideal as creating the `labelSet` can often be an expensive operation. This is why instruments are created and stored in a `Map` according to the route key.

#### Initialize and register a metrics exporter
Counting metrics is only useful if we can export them somewhere that we can see them. For this, we're going to use prometheus. Creating and registering a metrics exporter is much like the tracing exporter above. First we will need to install the prometheus exporter.
Expand Down Expand Up @@ -287,17 +287,17 @@ const requestCount = meter.createCounter("requests", {
description: "Count all incoming requests"
});
const handles = new Map();
const instruments = new Map();
module.exports.countAllRequests = () => {
return (req, res, next) => {
if (!handles.has(req.path)) {
if (!instruments.has(req.path)) {
const labelSet = meter.labels({ route: req.path });
const handle = requestCount.getHandle(labelSet);
handles.set(req.path, handle);
const instrument = requestCount.bind(labelSet);
instruments.set(req.path, instrument);
}
handles.get(req.path).add(1);
instruments.get(req.path).add(1);
next();
};
};
Expand Down
10 changes: 5 additions & 5 deletions getting-started/monitored-example/monitoring.js
Original file line number Diff line number Diff line change
Expand Up @@ -22,17 +22,17 @@ const requestCount = meter.createCounter("requests", {
description: "Count all incoming requests"
});

const handles = new Map();
const instruments = new Map();

module.exports.countAllRequests = () => {
return (req, res, next) => {
if (!handles.has(req.path)) {
if (!instruments.has(req.path)) {
const labelSet = meter.labels({ route: req.path });
const handle = requestCount.getHandle(labelSet);
handles.set(req.path, handle);
const instrument = requestCount.bind(labelSet);
instruments.set(req.path, instrument);
}

handles.get(req.path).add(1);
instruments.get(req.path).add(1);
next();
};
};
84 changes: 47 additions & 37 deletions packages/opentelemetry-core/src/metrics/NoopMeter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,14 @@
*/

import {
CounterHandle,
CounterInstrument,
DistributedContext,
GaugeHandle,
GaugeInstrument,
Meter,
Metric,
MetricOptions,
MetricUtils,
MeasureHandle,
MeasureInstrument,
SpanContext,
LabelSet,
Labels,
Expand All @@ -40,7 +40,10 @@ export class NoopMeter implements Meter {
* @param name the name of the metric.
* @param [options] the metric options.
*/
createMeasure(name: string, options?: MetricOptions): Metric<MeasureHandle> {
createMeasure(
name: string,
options?: MetricOptions
): Metric<MeasureInstrument> {
return NOOP_MEASURE_METRIC;
}

Expand All @@ -49,7 +52,10 @@ export class NoopMeter implements Meter {
* @param name the name of the metric.
* @param [options] the metric options.
*/
createCounter(name: string, options?: MetricOptions): Metric<CounterHandle> {
createCounter(
name: string,
options?: MetricOptions
): Metric<CounterInstrument> {
return NOOP_COUNTER_METRIC;
}

Expand All @@ -58,7 +64,7 @@ export class NoopMeter implements Meter {
* @param name the name of the metric.
* @param [options] the metric options.
*/
createGauge(name: string, options?: MetricOptions): Metric<GaugeHandle> {
createGauge(name: string, options?: MetricOptions): Metric<GaugeInstrument> {
return NOOP_GAUGE_METRIC;
}

Expand All @@ -68,33 +74,33 @@ export class NoopMeter implements Meter {
}

export class NoopMetric<T> implements Metric<T> {
private readonly _handle: T;
private readonly _instrument: T;

constructor(handle: T) {
this._handle = handle;
constructor(instrument: T) {
this._instrument = instrument;
}
/**
* Returns a Handle associated with specified LabelSet.
* It is recommended to keep a reference to the Handle instead of always
* Returns an Instrument associated with specified LabelSet.
* It is recommended to keep a reference to the Instrument instead of always
* calling this method for every operations.
* @param labels the canonicalized LabelSet used to associate with this metric handle.
* @param labels the canonicalized LabelSet used to associate with this metric instrument.
*/
getHandle(labels: LabelSet): T {
return this._handle;
bind(labels: LabelSet): T {
return this._instrument;
}

/**
* Returns a Handle for a metric with all labels not set.
* Returns an Instrument for a metric with all labels not set.
*/
getDefaultHandle(): T {
return this._handle;
getDefaultInstrument(): T {
return this._instrument;
}

/**
* Removes the Handle from the metric, if it is present.
* @param labels the canonicalized LabelSet used to associate with this metric handle.
* Removes the Instrument from the metric, if it is present.
* @param labels the canonicalized LabelSet used to associate with this metric instrument.
*/
removeHandle(labels: LabelSet): void {
removeInstrument(labels: LabelSet): void {
// @todo: implement this method
return;
}
Expand All @@ -111,21 +117,21 @@ export class NoopMetric<T> implements Metric<T> {
}
}

export class NoopCounterMetric extends NoopMetric<CounterHandle>
export class NoopCounterMetric extends NoopMetric<CounterInstrument>
implements Pick<MetricUtils, 'add'> {
add(value: number, labelSet: LabelSet) {
this.getHandle(labelSet).add(value);
this.bind(labelSet).add(value);
}
}

export class NoopGaugeMetric extends NoopMetric<GaugeHandle>
export class NoopGaugeMetric extends NoopMetric<GaugeInstrument>
implements Pick<MetricUtils, 'set'> {
set(value: number, labelSet: LabelSet) {
this.getHandle(labelSet).set(value);
this.bind(labelSet).set(value);
}
}

export class NoopMeasureMetric extends NoopMetric<MeasureHandle>
export class NoopMeasureMetric extends NoopMetric<MeasureInstrument>
implements Pick<MetricUtils, 'record'> {
record(
value: number,
Expand All @@ -134,28 +140,28 @@ export class NoopMeasureMetric extends NoopMetric<MeasureHandle>
spanContext?: SpanContext
) {
if (typeof distContext === 'undefined') {
this.getHandle(labelSet).record(value);
this.bind(labelSet).record(value);
} else if (typeof spanContext === 'undefined') {
this.getHandle(labelSet).record(value, distContext);
this.bind(labelSet).record(value, distContext);
} else {
this.getHandle(labelSet).record(value, distContext, spanContext);
this.bind(labelSet).record(value, distContext, spanContext);
}
}
}

export class NoopCounterHandle implements CounterHandle {
export class NoopCounterInstrument implements CounterInstrument {
add(value: number): void {
return;
}
}

export class NoopGaugeHandle implements GaugeHandle {
export class NoopGaugeInstrument implements GaugeInstrument {
set(value: number): void {
return;
}
}

export class NoopMeasureHandle implements MeasureHandle {
export class NoopMeasureInstrument implements MeasureInstrument {
record(
value: number,
distContext?: DistributedContext,
Expand All @@ -165,13 +171,17 @@ export class NoopMeasureHandle implements MeasureHandle {
}
}

export const NOOP_GAUGE_HANDLE = new NoopGaugeHandle();
export const NOOP_GAUGE_METRIC = new NoopGaugeMetric(NOOP_GAUGE_HANDLE);
export const NOOP_GAUGE_INSTRUMENT = new NoopGaugeInstrument();
export const NOOP_GAUGE_METRIC = new NoopGaugeMetric(NOOP_GAUGE_INSTRUMENT);

export const NOOP_COUNTER_HANDLE = new NoopCounterHandle();
export const NOOP_COUNTER_METRIC = new NoopCounterMetric(NOOP_COUNTER_HANDLE);
export const NOOP_COUNTER_INSTRUMENT = new NoopCounterInstrument();
export const NOOP_COUNTER_METRIC = new NoopCounterMetric(
NOOP_COUNTER_INSTRUMENT
);

export const NOOP_MEASURE_HANDLE = new NoopMeasureHandle();
export const NOOP_MEASURE_METRIC = new NoopMeasureMetric(NOOP_MEASURE_HANDLE);
export const NOOP_MEASURE_INSTRUMENT = new NoopMeasureInstrument();
export const NOOP_MEASURE_METRIC = new NoopMeasureMetric(
NOOP_MEASURE_INSTRUMENT
);

export const NOOP_LABEL_SET = {} as LabelSet;
32 changes: 16 additions & 16 deletions packages/opentelemetry-core/test/metrics/NoopMeter.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@
import * as assert from 'assert';
import {
NoopMeter,
NOOP_GAUGE_HANDLE,
NOOP_GAUGE_INSTRUMENT,
NOOP_GAUGE_METRIC,
NOOP_COUNTER_HANDLE,
NOOP_COUNTER_INSTRUMENT,
NOOP_COUNTER_METRIC,
NOOP_MEASURE_HANDLE,
NOOP_MEASURE_INSTRUMENT,
NOOP_MEASURE_METRIC,
} from '../../src/metrics/NoopMeter';
import { Labels } from '@opentelemetry/types';
Expand All @@ -37,20 +37,20 @@ describe('NoopMeter', () => {
counter.setCallback(() => {
assert.fail('callback occurred');
});
counter.getHandle(labelSet).add(1);
counter.getDefaultHandle().add(1);
counter.removeHandle(labelSet);
counter.bind(labelSet).add(1);
counter.getDefaultInstrument().add(1);
counter.removeInstrument(labelSet);

// ensure the correct noop const is returned
assert.strictEqual(counter, NOOP_COUNTER_METRIC);
assert.strictEqual(counter.getHandle(labelSet), NOOP_COUNTER_HANDLE);
assert.strictEqual(counter.getDefaultHandle(), NOOP_COUNTER_HANDLE);
assert.strictEqual(counter.bind(labelSet), NOOP_COUNTER_INSTRUMENT);
assert.strictEqual(counter.getDefaultInstrument(), NOOP_COUNTER_INSTRUMENT);
counter.clear();

const measure = meter.createMeasure('some-name');
measure.getDefaultHandle().record(1);
measure.getDefaultHandle().record(1, { key: { value: 'value' } });
measure.getDefaultHandle().record(
measure.getDefaultInstrument().record(1);
measure.getDefaultInstrument().record(1, { key: { value: 'value' } });
measure.getDefaultInstrument().record(
1,
{ key: { value: 'value' } },
{
Expand All @@ -61,16 +61,16 @@ describe('NoopMeter', () => {

// ensure the correct noop const is returned
assert.strictEqual(measure, NOOP_MEASURE_METRIC);
assert.strictEqual(measure.getDefaultHandle(), NOOP_MEASURE_HANDLE);
assert.strictEqual(measure.getHandle(labelSet), NOOP_MEASURE_HANDLE);
assert.strictEqual(measure.getDefaultInstrument(), NOOP_MEASURE_INSTRUMENT);
assert.strictEqual(measure.bind(labelSet), NOOP_MEASURE_INSTRUMENT);

const gauge = meter.createGauge('some-name');
gauge.getDefaultHandle().set(1);
gauge.getDefaultInstrument().set(1);

// ensure the correct noop const is returned
assert.strictEqual(gauge, NOOP_GAUGE_METRIC);
assert.strictEqual(gauge.getDefaultHandle(), NOOP_GAUGE_HANDLE);
assert.strictEqual(gauge.getHandle(labelSet), NOOP_GAUGE_HANDLE);
assert.strictEqual(gauge.getDefaultInstrument(), NOOP_GAUGE_INSTRUMENT);
assert.strictEqual(gauge.bind(labelSet), NOOP_GAUGE_INSTRUMENT);

const options = {
component: 'tests',
Expand Down
4 changes: 2 additions & 2 deletions packages/opentelemetry-exporter-collector/src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -119,8 +119,8 @@ export interface LibraryInfo {
/**
* A pointer from the current span to another span in the same trace or in a
* different trace. For example, this can be used in batching operations, where
* a single batch handler processes multiple requests from different traces or
* when the handler receives a request from a different project.
* a single batch instrument processes multiple requests from different traces or
* when the instrument receives a request from a different project.
*/
export interface Link {
/**
Expand Down
8 changes: 4 additions & 4 deletions packages/opentelemetry-exporter-prometheus/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,10 +36,10 @@ meter.addExporter(exporter);
const counter = meter.createCounter('metric_name');
counter.add(10, meter.labels({ [key]: 'value' }));

// Record data using Handle: It is recommended to keep a reference to the Handle instead of
// always calling `getHandle()` method for every operations.
const handle = counter.getHandle(meter.labels({ [key]: 'value' }));
handle.add(10);
// Record data using Instrument: It is recommended to keep a reference to the Instrument instead of
// always calling `bind()` method for every operations.
const instrument = counter.bind(meter.labels({ [key]: 'value' }));
instrument.add(10);

// .. some other work

Expand Down
Loading

0 comments on commit 9e8d389

Please sign in to comment.