From 847b3f32cdbafc429cae98c55ed0db47b47ef7d2 Mon Sep 17 00:00:00 2001 From: Chris H-C Date: Wed, 23 Oct 2024 13:52:07 -0400 Subject: [PATCH] Add docs for new metric type 'labeled_quantity' --- docs/user/SUMMARY.md | 1 + docs/user/reference/metrics/index.md | 2 + .../reference/metrics/labeled_quantity.md | 168 ++++++++++++++++++ 3 files changed, 171 insertions(+) create mode 100644 docs/user/reference/metrics/labeled_quantity.md diff --git a/docs/user/SUMMARY.md b/docs/user/SUMMARY.md index 94c7de3483..6be3c607a8 100644 --- a/docs/user/SUMMARY.md +++ b/docs/user/SUMMARY.md @@ -85,6 +85,7 @@ - [Custom Distribution](reference/metrics/custom_distribution.md) - [Labeled Custom Distributions](reference/metrics/labeled_custom_distributions.md) - [Quantity](reference/metrics/quantity.md) + - [Labeled Quantities](reference/metrics/labeled_quantity.md) - [Rate](reference/metrics/rate.md) - [Text](reference/metrics/text.md) - [Object](reference/metrics/object.md) diff --git a/docs/user/reference/metrics/index.md b/docs/user/reference/metrics/index.md index 422635f770..f49db54762 100644 --- a/docs/user/reference/metrics/index.md +++ b/docs/user/reference/metrics/index.md @@ -38,6 +38,8 @@ There are different metrics to choose from, depending on what you want to achiev * [Quantity](quantity.md): Used to record a single non-negative integer value. For example, the width of the display in pixels. +* [Labeled Quantity](labeled_quantity.md): Used to record multiple non-negative integer values. For example, the dimensions of the display in pixels. + * [Rate](rate.md): Used to record the rate something happens relative to some other thing. For example, the number of HTTP connections that experienced an error relative to the number of total HTTP connections made. diff --git a/docs/user/reference/metrics/labeled_quantity.md b/docs/user/reference/metrics/labeled_quantity.md new file mode 100644 index 0000000000..12bbd4a84c --- /dev/null +++ b/docs/user/reference/metrics/labeled_quantity.md @@ -0,0 +1,168 @@ +# Labeled Quantities + +Labeled quantity metrics are used to record different related non-negative integer values. +For example, the width and height of the display in pixels. + +{{#include ../../../shared/blockquote-warning.html}} + +## Do not use Labeled Quantity metrics for counting + +> If you need to _count_ some things (e.g. the number of times buttons are pressed) +> prefer using the [Labeled Counter](./labeled_counters.md) metric type, which has a specific API for counting things. + +## Recording API + +### `set` + +Sets a quantity metric to a specific value for the given label. + +{{#include ../../../shared/tab_header.md}} + +
+
+
+
+
+ +```Rust +use glean_metrics::gfx; + +gfx::display.get("width").set(width); +gfx::display.get("height").set(height); +``` +
+ +
+
+ +{{#include ../../../shared/tab_footer.md}} + +#### Limits + +* Quantities must be non-negative integers or 0. + +#### Recorded errors + +* [`invalid_value`](../../user/metrics/error-reporting.md): if a negative value is passed in. +* [`invalid_type`](../../user/metrics/error-reporting.md): if a floating point or non-number value is given. +{{#include ../../_includes/label-errors.md}} + +## Testing API + +### `testGetValue` + +Gets the recorded value for a given label in a labeled quantity metric. +Returns the quantity value if data is stored. +Returns a language-specific empty/null value if no data is stored. +Has an optional argument to specify the name of the ping you wish to retrieve data from, except +in Rust where it's required. `None` or no argument will default to the first value found for `send_in_pings`. + +{{#include ../../../shared/tab_header.md}} + +
+
+
+
+
+ +```Rust +use glean_metrics::gfx; + +// Was anything recorded? +assert_eq!(433, gfx::display.get("width").test_get_value(None).unwrap()); +assert_eq!(42, gfx::display.get("height").test_get_value(None).unwrap()); +``` +
+ +
+
+ +{{#include ../../../shared/tab_footer.md}} + +### `testGetNumRecordedErrors` + +Gets the number of errors recorded for a given label in a labeled quantity metric. + +{{#include ../../../shared/tab_header.md}} + +
+
+
+
+
+ +```Rust +use glean::ErrorType; +use glean_metrics::gfx; + +assert_eq!( + 0, + gfx::display.get("width").test_get_num_recorded_errors( + ErrorType::InvalidValue, + None + ) +); +assert_eq!( + 0, + gfx::display.get("height").test_get_num_recorded_errors( + ErrorType::InvalidValue, + None + ) +); +``` +
+ +
+
+ +{{#include ../../../shared/tab_footer.md}} + +## Metric parameters + +Example quantity metric definition: + +```yaml +gfx: + display: + type: labeled_quantity + description: > + The dimensions of the display, in pixels. + For one-dimensional displays, uses only "width". + Two-dimensional displays add "height". + 3D displays gain "depth". + bugs: + - https://bugzilla.mozilla.org/000000 + data_reviews: + - https://bugzilla.mozilla.org/show_bug.cgi?id=000000#c3 + notification_emails: + - me@mozilla.com + expires: 2020-10-01 + unit: pixels + labels: + - width + - height + - depth +``` + +For a full reference on metrics parameters common to all metric types, +refer to the [metrics YAML registry format](../yaml/metrics.md) reference page. + +### Extra metric parameters + +#### `unit` + +Labeled Quantities have the required `unit` parameter, which is a free-form string for documentation purposes. + +{{#include ../../_includes/labels-parameter.md}} + +## Data questions + +* What are the dimensions of the display, in pixels? + +## Limits + +{{#include ../../_includes/label-limits.md}} + +## Reference + +* Rust API docs: [`LabeledMetric`](../../../docs/glean/private/struct.LabeledMetric.html), [`QuantityMetric`](../../../docs/glean/private/quantity/struct.QuantityMetric.html)