feat(metrics): add UpDownCounter to Buffered Metrics and RuntimeMetricMeter (#2007)

Co-authored-by: James Watkins-Harvey <james.watkinsharvey@temporal.io>

Author: gibbonjj

packages/common/src/metrics.ts

@@ -40,6 +40,15 @@ export interface MetricMeter {
    */
   createGauge(name: string, valueType?: NumericMetricValueType, unit?: string, description?: string): MetricGauge;
 
+  /**
+   * Create a new up-down counter metric that supports adding signed values.
+   *
+   * @param name Name for the up-down counter metric.
+   * @param unit Unit for the up-down counter metric. Optional.
+   * @param description Description for the up-down counter metric. Optional.
+   */
+  createUpDownCounter?(name: string, unit?: string, description?: string): MetricUpDownCounter;
+
   /**
    * Return a clone of this meter, with additional tags. All metrics created off the meter will
    * have the tags.
@@ -104,7 +113,7 @@ export type NumericMetricValueType = 'int' | 'float';
  *
  * @experimental The Metric API is an experimental feature and may be subject to change.
  */
-export type MetricKind = 'counter' | 'histogram' | 'gauge';
+export type MetricKind = 'counter' | 'histogram' | 'gauge' | 'up-down-counter';
 
 /**
  * A metric that supports adding values as a counter.
@@ -181,6 +190,31 @@ export interface MetricGauge extends Metric {
   kind: 'gauge';
 }
 
+/**
+ * A metric that supports adding signed values as an up-down counter.
+ *
+ * @experimental The Metric API is an experimental feature and may be subject to change.
+ */
+export interface MetricUpDownCounter extends Metric {
+  /**
+   * Add the given value to the up-down counter. Value may be negative.
+   *
+   * @param value Value to add (can be positive or negative).
+   * @param extraTags Extra tags if any.
+   */
+  add(value: number, extraTags?: MetricTags): void;
+
+  /**
+   * Return a clone of this up-down counter, with additional tags.
+   *
+   * @param tags Tags to append to existing tags.
+   */
+  withTags(tags: MetricTags): MetricUpDownCounter;
+
+  kind: 'up-down-counter';
+  valueType: 'int';
+}
+
 ////////////////////////////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -248,6 +282,23 @@ class NoopMetricMeter implements MetricMeter {
     };
   }
 
+  createUpDownCounter(name: string, unit?: string, description?: string): MetricUpDownCounter {
+    return {
+      name,
+      unit,
+      description,
+
+      kind: 'up-down-counter',
+      valueType: 'int',
+
+      add(_value, _extraTags) {},
+
+      withTags(_extraTags) {
+        return this;
+      },
+    };
+  }
+
   withTags(_extraTags: MetricTags): MetricMeter {
     return this;
   }
@@ -326,6 +377,16 @@ export class MetricMeterWithComposedTags implements MetricMeter {
     return new MetricGaugeWithComposedTags(parentGauge, this.contributors);
   }
 
+  createUpDownCounter(name: string, unit?: string, description?: string): MetricUpDownCounter {
+    // FIXME: Remove this guard once up-down-counter support is complete on all MetricMeter
+    // implementations and `createUpDownCounter` is no longer optional on MetricMeter.
+    if (!this.parentMeter.createUpDownCounter) {
+      throw new Error('createUpDownCounter is not supported by the underlying meter');
+    }
+    const parentCounter = this.parentMeter.createUpDownCounter(name, unit, description);
+    return new MetricUpDownCounterWithComposedTags(parentCounter, this.contributors);
+  }
+
   withTags(tags: MetricTags): MetricMeter {
     return MetricMeterWithComposedTags.compose(this, tags);
   }
@@ -443,6 +504,42 @@ class MetricGaugeWithComposedTags implements MetricGauge {
   }
 }
 
+/**
+ * @internal
+ * @hidden
+ */
+class MetricUpDownCounterWithComposedTags implements MetricUpDownCounter {
+  public readonly kind = 'up-down-counter';
+  public readonly valueType = 'int';
+
+  constructor(
+    private parentCounter: MetricUpDownCounter,
+    private contributors: MetricTagsOrFunc[]
+  ) {}
+
+  add(value: number, extraTags?: MetricTags | undefined): void {
+    this.parentCounter.add(value, resolveTags(this.contributors, extraTags));
+  }
+
+  withTags(extraTags: MetricTags): MetricUpDownCounter {
+    const contributors = appendToChain(this.contributors, extraTags);
+    if (contributors === undefined) return this;
+    return new MetricUpDownCounterWithComposedTags(this.parentCounter, contributors);
+  }
+
+  get name(): string {
+    return this.parentCounter.name;
+  }
+
+  get unit(): string | undefined {
+    return this.parentCounter.unit;
+  }
+
+  get description(): string | undefined {
+    return this.parentCounter.description;
+  }
+}
+
 function resolveTags(contributors: MetricTagsOrFunc[], extraTags?: MetricTags): MetricTags {
   const resolved = {};
   for (const contributor of contributors) {