# Rate

Used to count how often something happens relative to how often something else happens. Like how many documents use a particular CSS Property, or how many HTTP connections had an error. You can think of it like a fraction, with a numerator and a denominator.

All rates start without a value. A rate with a numerator of 0 is valid and will be sent to ensure we capture the "no errors happened" or "no use counted" cases.

## Let the Glean metric do the counting

When using a rate metric, it is important to let the Glean metric do the counting. Using your own variable for counting and setting the metric yourself could be problematic: ping scheduling will make it difficult to ensure the metric is at the correct value at the correct time. Instead, count to the numerator and denominator as you go.

## Recording API

### addToNumerator / addToDenominator

Count numerator and denominator individually:

use glean_metrics::*;

}



#### External Denominators

If the rate uses an external denominator, adding to the denominator must be done through the denominator's counter API:

use glean_metrics;

}



C++

#include "mozilla/glean/GleanMetrics.h"

}


JavaScript

if (aHadError) {
}


#### Recorded errors

• invalid_value: If either numerator or denominator is incremented by a negative value.

#### Limits

• Numerator and Denominator only increment.
• Numerator and Denominator saturate at the largest value that can be represented as a 32-bit signed integer (2147483647).

## Testing API

### testGetValue

use glean_metrics::*;

assert_eq!((1, 1), network::http_connection_error.test_get_value(None).unwrap());


C++

#include "mozilla/glean/GleanMetrics.h"

auto pair = mozilla::glean::network::http_connection_error.TestGetValue().unwrap();
ASSERT_EQ(1, pair.first);
ASSERT_EQ(1, pair.second);


JavaScript

// testGetValue will throw NS_ERROR_LOSS_OF_SIGNIFICANT_DATA on error.
Assert.deepEqual(
{ numerator: 1, denominator: 1 },
Glean.network.httpConnectionError.testGetValue()
);


### testGetNumRecordedErrors

use glean_metrics::*;
use glean::ErrorType;

assert_eq!(
0,
network::http_connection_error.test_get_num_recorded_errors(
ErrorType::InvalidValue
)
);


## Metric parameters

Example rate metric definition:

network:
http_connection_error:
type: rate
description: >
How many HTTP connections error out out of the total connections made.
bugs:
- https://bugzilla.mozilla.org/000000
data_reviews:
- https://bugzilla.mozilla.org/show_bug.cgi?id=000000#c3
- me@mozilla.com
expires: 2020-10-01


For a full reference on metrics parameters common to all metric types, refer to the metrics YAML registry format reference page.

### External Denominators

If several rates share the same denominator then the denominator should be defined as a counter and shared between rates using the denominator_metric property:

network:
http_connections:
type: counter
description: >
Total number of http connections made.
...

http_connection_error:
type: rate
description: >
How many HTTP connections error out out of the total connections made.
denominator_metric: network.http_connections
...

http_connection_slow:
type: rate
description: >
How many HTTP connections were slow, out of the total connections made.
denominator_metric: network.http_connections
...


## Data Questions

• How often did an HTTP connection error?
• How many documents used a given CSS Property?