feat: implement labelset

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

@@ -23,6 +23,8 @@ import {
   MetricOptions,
   MeasureHandle,
   SpanContext,
+  LabelSet,
+  Labels,
 } from '@opentelemetry/types';
 
 /**
@@ -58,6 +60,10 @@ export class NoopMeter implements Meter {
   createGauge(name: string, options?: MetricOptions): Metric<GaugeHandle> {
     return NOOP_GAUGE_METRIC;
   }
+
+  labels(labels: Labels): LabelSet {
+    return NOOP_LABEL_SET;
+  }
 }
 
 export class NoopMetric<T> implements Metric<T> {
@@ -67,12 +73,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 +91,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 +144,5 @@ export const NOOP_MEASURE_HANDLE = new NoopMeasureHandle();
 export const NOOP_MEASURE_METRIC = new NoopMetric<MeasureHandle>(
   NOOP_MEASURE_HANDLE
 );
+
+export const NOOP_LABEL_SET = {} 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 { Labels } from '@opentelemetry/types';
 
 describe('NoopMeter', () => {
   it('should not crash', () => {
     const meter = new NoopMeter();
     const counter = meter.createCounter('some-name');
+    const labels = {} as Labels;
+    const labelSet = meter.labels(labels);
+
     // ensure NoopMetric does not crash.
     counter.setCallback(() => {
       assert.fail('callback occurred');
     });
-    counter.getHandle(['val1', 'val2']).add(1);
+    counter.getHandle(labelSet).add(1);
     counter.getDefaultHandle().add(1);
-    counter.removeHandle(['val1', 'val2']);
+    counter.removeHandle(labelSet);
 
     // 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(labelSet), 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(labelSet), 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(labelSet), 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 _labelSet: types.LabelSet,
     private readonly _logger: types.Logger
   ) {}
 
@@ -50,23 +49,25 @@ export class CounterHandle implements types.CounterHandle {
    */
   getTimeSeries(timestamp: types.HrTime): TimeSeries {
     return {
-      labelValues: this._labelValues.map(value => ({ value })),
+      labelValues: Object.values(this._labelSet.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 _labelSet: types.LabelSet,
     private readonly _logger: types.Logger
   ) {}
 
@@ -88,7 +89,9 @@ export class GaugeHandle implements types.GaugeHandle {
    */
   getTimeSeries(timestamp: types.HrTime): TimeSeries {
     return {
-      labelValues: this._labelValues.map(value => ({ value })),
+      labelValues: Object.values(this._labelSet.labels).map(value => ({
+        value,
+      })),
       points: [{ value: this._data, timestamp }],
     };
   }

packages/opentelemetry-metrics/src/Meter.ts

@@ -27,6 +27,7 @@ import {
   DEFAULT_METRIC_OPTIONS,
   DEFAULT_CONFIG,
   MeterConfig,
+  LabelSet,
 } from './types';
 
 /**
@@ -116,6 +117,28 @@ export class Meter implements types.Meter {
     return new GaugeMetric(name, opt);
   }
 
+  /**
+   * Provide a pre-computed re-useable LabelSet by
+   * converting the unordered labels into a canonicalized
+   * set of lables with a unique labelSetKey, useful for pre-aggregation.
+   * @param labels user provided unordered Labels.
+   */
+  labels(labels: types.Labels): types.LabelSet {
+    let keys = Object.keys(labels).sort();
+    let labelSetKey = keys.reduce((result, key) => {
+      if (result.length > 2) {
+        result += ',';
+      }
+      result = result + key + ':' + labels[key];
+      return result;
+    }, '|#');
+    let sortedLabels = {} as types.Labels;
+    keys.forEach(key => {
+      sortedLabels[key] = labels[key];
+    });
+    return new LabelSet(labelSetKey, sortedLabels);
+  }
+
   /**
    * Ensure a metric name conforms to the following rules:
    *

packages/opentelemetry-metrics/src/Metric.ts

@@ -15,7 +15,6 @@
  */
 
 import * as types from '@opentelemetry/types';
-import { hashLabelValues } from './Utils';
 import { CounterHandle, GaugeHandle } from './Handle';
 import { MetricOptions } from './types';
 
@@ -33,17 +32,17 @@ 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 labelSet the canonicalized LabelSet used to associate with this metric handle.
    */
-  getHandle(labelValues: string[]): T {
-    const hash = hashLabelValues(labelValues);
-    if (this._handles.has(hash)) return this._handles.get(hash)!;
+  getHandle(labelSet: types.LabelSet): T {
+    if (this._handles.has(labelSet.labelSetKey))
+      return this._handles.get(labelSet.labelSetKey)!;
 
-    const handle = this._makeHandle(labelValues);
-    this._handles.set(hash, handle);
+    const handle = this._makeHandle(labelSet);
+    this._handles.set(labelSet.labelSetKey, handle);
     return handle;
   }
 
@@ -58,10 +57,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 labelSet the canonicalized LabelSet used to associate with this metric handle.
    */
-  removeHandle(labelValues: string[]): void {
-    this._handles.delete(hashLabelValues(labelValues));
+  removeHandle(labelSet: types.LabelSet): void {
+    this._handles.delete(labelSet.labelSetKey);
   }
 
   /**
@@ -77,19 +76,19 @@ export abstract class Metric<T> implements types.Metric<T> {
     return;
   }
 
-  protected abstract _makeHandle(labelValues: string[]): T;
+  protected abstract _makeHandle(labelSet: 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(labelSet: types.LabelSet): CounterHandle {
     return new CounterHandle(
       this._disabled,
       this._monotonic,
-      labelValues,
+      labelSet,
       this._logger
     );
   }
@@ -100,11 +99,11 @@ export class GaugeMetric extends Metric<GaugeHandle> {
   constructor(name: string, options: MetricOptions) {
     super(name, options);
   }
-  protected _makeHandle(labelValues: string[]): GaugeHandle {
+  protected _makeHandle(labelSet: types.LabelSet): GaugeHandle {
     return new GaugeHandle(
       this._disabled,
       this._monotonic,
-      labelValues,
+      labelSet,
       this._logger
     );
   }

packages/opentelemetry-metrics/src/Utils.ts

@@ -13,15 +13,3 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
-const COMMA_SEPARATOR = ',';
-
-/**
- * Returns a string(comma separated) from the list of label values.
- *
- * @param labelValues The list of the label values.
- * @returns The hashed label values string.
- */
-export function hashLabelValues(labelValues: string[]): string {
-  return labelValues.sort().join(COMMA_SEPARATOR);
-}

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

@@ -124,7 +124,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[];

packages/opentelemetry-metrics/src/types.ts

@@ -15,7 +15,7 @@
  */
 
 import { LogLevel } from '@opentelemetry/core';
-import { Logger } from '@opentelemetry/types';
+import { Logger, Labels } from '@opentelemetry/types';
 
 /** Options needed for SDK metric creation. */
 export interface MetricOptions {
@@ -65,3 +65,13 @@ export const DEFAULT_METRIC_OPTIONS = {
   unit: '1',
   labelKeys: [],
 };
+
+export class LabelSet implements LabelSet {
+  labelSetKey: string;
+  labels: Labels;
+
+  constructor(labelSetKey: string, labels: Labels) {
+    this.labelSetKey = labelSetKey;
+    this.labels = labels;
+  }
+}