feat: implement labelset

packages/opentelemetry-core/src/metrics/NoopMeter.ts

@@ -23,6 +23,7 @@ import {
   MetricOptions,
   MeasureHandle,
   SpanContext,
+  LabelSet,
 } from '@opentelemetry/types';
 
 /**
@@ -58,6 +59,10 @@ export class NoopMeter implements Meter {
   createGauge(name: string, options?: MetricOptions): Metric<GaugeHandle> {
     return NOOP_GAUGE_METRIC;
   }
+
+  labels(labels: LabelSet): LabelSet {
+    return NOOP_METER;
+  }
 }
 
 export class NoopMetric<T> implements Metric<T> {
@@ -67,12 +72,12 @@ export class NoopMetric<T> implements Metric<T> {
     this._handle = handle;
   }
   /**
-   * Returns a Handle associated with specified label values.
+   * Returns a Handle associated with specified LabelSet.
    * It is recommended to keep a reference to the Handle instead of always
    * calling this method for every operations.
-   * @param labelValues the list of label values.
+   * @param labels the canonicalized LabelSet used to associate with this metric handle.
    */
-  getHandle(labelValues: string[]): T {
+  getHandle(labels: LabelSet): T {
     return this._handle;
   }
 
@@ -85,9 +90,10 @@ export class NoopMetric<T> implements Metric<T> {
 
   /**
    * Removes the Handle from the metric, if it is present.
-   * @param labelValues the list of label values.
+   * @param labels the canonicalized LabelSet used to associate with this metric handle.
    */
-  removeHandle(labelValues: string[]): void {
+  removeHandle(labels: LabelSet): void {
+    // @todo: implement this method
     return;
   }
 
@@ -137,3 +143,5 @@ export const NOOP_MEASURE_HANDLE = new NoopMeasureHandle();
 export const NOOP_MEASURE_METRIC = new NoopMetric<MeasureHandle>(
   NOOP_MEASURE_HANDLE
 );
+
+export const NOOP_METER = {} as LabelSet;

packages/opentelemetry-core/test/metrics/NoopMeter.test.ts

@@ -24,25 +24,26 @@ import {
   NOOP_MEASURE_HANDLE,
   NOOP_MEASURE_METRIC,
 } from '../../src/metrics/NoopMeter';
+import { LabelSet } from '@opentelemetry/types';
 
 describe('NoopMeter', () => {
   it('should not crash', () => {
     const meter = new NoopMeter();
     const counter = meter.createCounter('some-name');
+    const key1 = 'key1';
+    const key2 = 'key2';
+    const labels: LabelSet = { [key1]: 'val1', [key2]: 'val2' };
     // ensure NoopMetric does not crash.
     counter.setCallback(() => {
       assert.fail('callback occurred');
     });
-    counter.getHandle(['val1', 'val2']).add(1);
+    counter.getHandle(labels).add(1);
     counter.getDefaultHandle().add(1);
-    counter.removeHandle(['val1', 'val2']);
+    counter.removeHandle(labels);
 
     // ensure the correct noop const is returned
     assert.strictEqual(counter, NOOP_COUNTER_METRIC);
-    assert.strictEqual(
-      counter.getHandle(['val1', 'val2']),
-      NOOP_COUNTER_HANDLE
-    );
+    assert.strictEqual(counter.getHandle(labels), NOOP_COUNTER_HANDLE);
     assert.strictEqual(counter.getDefaultHandle(), NOOP_COUNTER_HANDLE);
     counter.clear();
 
@@ -61,23 +62,19 @@ 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(['val1', 'val2']),
-      NOOP_MEASURE_HANDLE
-    );
+    assert.strictEqual(measure.getHandle(labels), NOOP_MEASURE_HANDLE);
 
     const gauge = meter.createGauge('some-name');
     gauge.getDefaultHandle().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(['val1', 'val2']), NOOP_GAUGE_HANDLE);
+    assert.strictEqual(gauge.getHandle(labels), NOOP_GAUGE_HANDLE);
 
     const options = {
       component: 'tests',
       description: 'the testing package',
-      labelKeys: ['key1', 'key2'],
     };
 
     const measureWithOptions = meter.createMeasure('some-name', options);

packages/opentelemetry-metrics/src/Handle.ts

@@ -19,16 +19,15 @@ import { TimeSeries } from './export/types';
 
 /**
  * CounterHandle allows the SDK to observe/record a single metric event. The
- * value of single handle in the `Counter` associated with specified label
- * values.
+ * value of single handle in the `Counter` associated with specified LabelSet.
  */
 export class CounterHandle implements types.CounterHandle {
   private _data = 0;
 
   constructor(
     private readonly _disabled: boolean,
     private readonly _monotonic: boolean,
-    private readonly _labelValues: string[],
+    private readonly _labels: types.LabelSet,
     private readonly _logger: types.Logger
   ) {}
 
@@ -50,23 +49,23 @@ export class CounterHandle implements types.CounterHandle {
    */
   getTimeSeries(timestamp: types.HrTime): TimeSeries {
     return {
-      labelValues: this._labelValues.map(value => ({ value })),
+      labelValues: Object.values(this._labels).map(value => ({ value })),
       points: [{ value: this._data, timestamp }],
     };
   }
 }
 
 /**
  * GaugeHandle allows the SDK to observe/record a single metric event. The
- * value of single handle in the `Gauge` associated with specified label values.
+ * value of single handle in the `Gauge` associated with specified LabelSet.
  */
 export class GaugeHandle implements types.GaugeHandle {
   private _data = 0;
 
   constructor(
     private readonly _disabled: boolean,
     private readonly _monotonic: boolean,
-    private readonly _labelValues: string[],
+    private readonly _labels: types.LabelSet,
     private readonly _logger: types.Logger
   ) {}
 
@@ -88,7 +87,7 @@ export class GaugeHandle implements types.GaugeHandle {
    */
   getTimeSeries(timestamp: types.HrTime): TimeSeries {
     return {
-      labelValues: this._labelValues.map(value => ({ value })),
+      labelValues: Object.values(this._labels).map(value => ({ value })),
       points: [{ value: this._data, timestamp }],
     };
   }

packages/opentelemetry-metrics/src/Meter.ts

@@ -93,4 +93,22 @@ export class Meter implements types.Meter {
     };
     return new GaugeMetric(name, opt);
   }
+
+  /**
+   * Provide a pre-computed re-useable LabelSet by
+   * converting the unordered LabelSet into a canonicalized
+   * set of lables, useful for pre-aggregation.
+   * @param labels user provided unordered LabelSet.
+   */
+  labels(labels: types.LabelSet): types.LabelSet {
+    return Object.keys(labels)
+      .sort()
+      .reduce(
+        (result, key) => {
+          result[key] = labels[key];
+          return result;
+        },
+        {} as types.LabelSet
+      );
+  }
 }

packages/opentelemetry-metrics/src/Metric.ts

@@ -33,16 +33,16 @@ export abstract class Metric<T> implements types.Metric<T> {
   }
 
   /**
-   * Returns a Handle associated with specified label values.
+   * Returns a Handle associated with specified LabelSet.
    * It is recommended to keep a reference to the Handle instead of always
    * calling this method for each operation.
-   * @param labelValues the list of label values.
+   * @param labels the canonicalized LabelSet used to associate with this metric handle.
    */
-  getHandle(labelValues: string[]): T {
-    const hash = hashLabelValues(labelValues);
+  getHandle(labels: types.LabelSet): T {
+    const hash = hashLabelValues(Object.values(labels));
     if (this._handles.has(hash)) return this._handles.get(hash)!;
 
-    const handle = this._makeHandle(labelValues);
+    const handle = this._makeHandle(labels);
     this._handles.set(hash, handle);
     return handle;
   }
@@ -58,10 +58,10 @@ export abstract class Metric<T> implements types.Metric<T> {
 
   /**
    * Removes the Handle from the metric, if it is present.
-   * @param labelValues the list of label values.
+   * @param labels the canonicalized LabelSet used to associate with this metric handle.
    */
-  removeHandle(labelValues: string[]): void {
-    this._handles.delete(hashLabelValues(labelValues));
+  removeHandle(labels: types.LabelSet): void {
+    this._handles.delete(hashLabelValues(Object.values(labels)));
   }
 
   /**
@@ -77,19 +77,19 @@ export abstract class Metric<T> implements types.Metric<T> {
     return;
   }
 
-  protected abstract _makeHandle(labelValues: string[]): T;
+  protected abstract _makeHandle(labels: types.LabelSet): T;
 }
 
 /** This is a SDK implementation of Counter Metric. */
 export class CounterMetric extends Metric<CounterHandle> {
   constructor(name: string, options: MetricOptions) {
     super(name, options);
   }
-  protected _makeHandle(labelValues: string[]): CounterHandle {
+  protected _makeHandle(labels: types.LabelSet): CounterHandle {
     return new CounterHandle(
       this._disabled,
       this._monotonic,
-      labelValues,
+      labels,
       this._logger
     );
   }
@@ -100,11 +100,11 @@ export class GaugeMetric extends Metric<GaugeHandle> {
   constructor(name: string, options: MetricOptions) {
     super(name, options);
   }
-  protected _makeHandle(labelValues: string[]): GaugeHandle {
+  protected _makeHandle(labels: types.LabelSet): GaugeHandle {
     return new GaugeHandle(
       this._disabled,
       this._monotonic,
-      labelValues,
+      labels,
       this._logger
     );
   }

packages/opentelemetry-metrics/src/Utils.ts

@@ -23,5 +23,5 @@ const COMMA_SEPARATOR = ',';
  * @returns The hashed label values string.
  */
 export function hashLabelValues(labelValues: string[]): string {
-  return labelValues.sort().join(COMMA_SEPARATOR);
+  return labelValues.join(COMMA_SEPARATOR);
 }

packages/opentelemetry-metrics/src/export/types.ts

@@ -22,7 +22,7 @@
  * opentelemetry-proto/opentelemetry/proto/metrics/v1/metrics.proto
  */
 
-import { HrTime } from '@opentelemetry/types';
+import { HrTime, LabelSet } from '@opentelemetry/types';
 import { Resource, ExportResult } from '@opentelemetry/base';
 
 export interface ReadableMetric {
@@ -63,6 +63,8 @@ export interface MetricDescriptor {
   readonly type: MetricDescriptorType;
   /** The label keys associated with the metric descriptor. */
   readonly labelKeys: string[];
+  /** The label set associated with the metric descriptor. */
+  readonly labels: LabelSet;
 }
 
 /**
@@ -124,7 +126,7 @@ export enum MetricDescriptorType {
 export interface TimeSeries {
   /**
    * The set of label values that uniquely identify this timeseries. Applies to
-   * all points. The order of label values must match that of label keys in the
+   * all points. The order of label values must match that of LabelSet keys in the
    * metric descriptor.
    */
   readonly labelValues: LabelValue[];