Introduce QuantityMetric (#281)

Author: ChinYing-Li

CHANGELOG.md

@@ -3,6 +3,7 @@
 [Full changelog](https://github.com/mozilla/glean.js/compare/v0.11.0...main)
 
 * [#279](https://github.com/mozilla/glean.js/pull/279): BUGFIX: Ensure only empty pings triggers logging of "empty ping" messages.
+* [#281](https://github.com/mozilla/glean.js/pull/281): Add QuantityMetric
 
 # v0.11.0 (2021-05-03)
 

glean/src/core/metrics/types/quantity.ts

@@ -0,0 +1,107 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import type { CommonMetricData } from "../index.js";
+import { MetricType } from "../index.js";
+import { isNumber } from "../../utils.js";
+import { Context } from "../../context.js";
+import { Metric } from "../metric.js";
+
+export class QuantityMetric extends Metric<number, number> {
+  constructor(v: unknown) {
+    super(v);
+  }
+
+  validate(v: unknown): v is number {
+    if (!isNumber(v)) {
+      return false;
+    }
+
+    if (v < 0) {
+      return false;
+    }
+
+    return true;
+  }
+
+  payload(): number {
+    return this._inner;
+  }
+}
+
+/**
+ * A quantity metric.
+ *
+ * Used to store quantity.
+ * The value can only be non-negative.
+ */
+class QuantityMetricType extends MetricType {
+  constructor(meta: CommonMetricData) {
+    super("quantity", meta);
+  }
+
+  /**
+   * An internal implemention of `set` that does not dispatch the recording task.
+   *
+   * # Important
+   *
+   * This is absolutely not meant to be used outside of Glean itself.
+   * It may cause multiple issues because it cannot guarantee
+   * that the recording of the metric will happen in order with other Glean API calls.
+   *
+   * @param instance The metric instance to record to.
+   * @param value The string we want to set to.
+   */
+  static async _private_setUndispatched(instance: QuantityMetricType, value: number): Promise<void> {
+    if (!instance.shouldRecord(Context.uploadEnabled)) {
+      return;
+    }
+
+    if (value < 0) {
+      console.warn(`Attempted to set an invalid value ${value}. Ignoring.`);
+      return;
+    }
+
+    if (value > Number.MAX_SAFE_INTEGER) {
+      console.warn(`Attempted to set a big value ${value}. Capped at ${Number.MAX_SAFE_INTEGER}.`);
+      value = Number.MAX_SAFE_INTEGER;
+    }
+
+    const metric = new QuantityMetric(value);
+    await Context.metricsDatabase.record(instance, metric);
+  }
+
+  /**
+   * Sets to the specified quantity value.
+   *
+   * @param value the value to set.
+   */
+  set(value: number): void {
+    Context.dispatcher.launch(() => QuantityMetricType._private_setUndispatched(this, value));
+  }
+
+  /**
+   * **Test-only API.**
+   *
+   * Gets the currently stored value as a number.
+   *
+   * This doesn't clear the stored value.
+   *
+   * TODO: Only allow this function to be called on test mode (depends on Bug 1682771).
+   *
+   * @param ping the ping from which we want to retrieve this metrics value from.
+   *        Defaults to the first value in `sendInPings`.
+   *
+   * @returns The value found in storage or `undefined` if nothing was found.
+   */
+  async testGetValue(ping: string = this.sendInPings[0]): Promise<number | undefined> {
+    let metric: number | undefined;
+    await Context.dispatcher.testLaunch(async () => {
+      metric = await Context.metricsDatabase.getMetric<number>(ping, this);
+    });
+    return metric;
+  }
+}
+
+export default QuantityMetricType;

glean/src/core/metrics/utils.ts

@@ -10,6 +10,7 @@ import { LabeledMetric } from "./types/labeled.js";
 import { BooleanMetric } from "./types/boolean.js";
 import { CounterMetric } from "./types/counter.js";
 import { DatetimeMetric } from "./types/datetime.js";
+import { QuantityMetric } from "./types/quantity";
 import { StringMetric } from "./types/string.js";
 import { TimespanMetric } from "./types/timespan.js";
 import { UUIDMetric } from "./types/uuid.js";
@@ -26,6 +27,7 @@ const METRIC_MAP: {
   "labeled_boolean": LabeledMetric,
   "labeled_counter": LabeledMetric,
   "labeled_string": LabeledMetric,
+  "quantity": QuantityMetric,
   "string": StringMetric,
   "timespan": TimespanMetric,
   "uuid": UUIDMetric,

glean/tests/core/metrics/quantity.spec.ts

@@ -0,0 +1,106 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import assert from "assert";
+import { Context } from "../../../src/core/context";
+
+import Glean from "../../../src/core/glean";
+import { Lifetime } from "../../../src/core/metrics/lifetime";
+import QuantityMetricType from "../../../src/core/metrics/types/quantity";
+
+describe("QuantityMetric", function() {
+  const testAppId = `gleanjs.test.${this.title}`;
+
+  beforeEach(async function() {
+    await Glean.testResetGlean(testAppId);
+  });
+
+  it("attempting to get the value of a metric that hasn't been recorded doesn't error", async function() {
+    const metric = new QuantityMetricType({
+      category: "aCategory",
+      name: "aQuantityMetric",
+      sendInPings: ["aPing", "twoPing", "threePing"],
+      lifetime: Lifetime.Ping,
+      disabled: false
+    });
+
+    assert.strictEqual(await metric.testGetValue("aPing"), undefined);
+  });
+
+  it("attempting to set when glean upload is disabled is a no-op", async function() {
+    Glean.setUploadEnabled(false);
+
+    const metric = new QuantityMetricType({
+      category: "aCategory",
+      name: "aQuantityMetric",
+      sendInPings: ["aPing", "twoPing", "threePing"],
+      lifetime: Lifetime.Ping,
+      disabled: false
+    });
+
+    metric.set(10);
+    assert.strictEqual(await metric.testGetValue("aPing"), undefined);
+  });
+
+  it("ping payload is correct", async function() {
+    const metric = new QuantityMetricType({
+      category: "aCategory",
+      name: "aQuantityMetric",
+      sendInPings: ["aPing"],
+      lifetime: Lifetime.Ping,
+      disabled: false
+    });
+
+    metric.set(10);
+    assert.strictEqual(await metric.testGetValue("aPing"), 10);
+
+    const snapshot = await Context.metricsDatabase.getPingMetrics("aPing", true);
+    assert.deepStrictEqual(snapshot, {
+      "quantity": {
+        "aCategory.aQuantityMetric": 10
+      }
+    });
+  });
+
+  it("set properly sets the value in all pings", async function() {
+    const metric = new QuantityMetricType({
+      category: "aCategory",
+      name: "aQuantityMetric",
+      sendInPings: ["aPing", "twoPing", "threePing"],
+      lifetime: Lifetime.Ping,
+      disabled: false
+    });
+
+    metric.set(0);
+    assert.strictEqual(await metric.testGetValue("aPing"), 0);
+    assert.strictEqual(await metric.testGetValue("twoPing"), 0);
+    assert.strictEqual(await metric.testGetValue("threePing"), 0);
+  });
+
+  it("must not set when passed negative", async function() {
+    const metric = new QuantityMetricType({
+      category: "aCategory",
+      name: "aQuantityMetric",
+      sendInPings: ["aPing"],
+      lifetime: Lifetime.Ping,
+      disabled: false
+    });
+
+    metric.set(-1);
+    assert.strictEqual(await metric.testGetValue("aPing"), undefined);
+  });
+
+  it("saturates at boundary", async function() {
+    const metric = new QuantityMetricType({
+      category: "aCategory",
+      name: "aQuantityMetric",
+      sendInPings: ["aPing"],
+      lifetime: Lifetime.Ping,
+      disabled: false
+    });
+
+    metric.set(Number.MAX_SAFE_INTEGER+1);
+    assert.strictEqual(await metric.testGetValue("aPing"), Number.MAX_SAFE_INTEGER);
+  });
+});