diff --git a/docs/dev/core/internal/payload.md b/docs/dev/core/internal/payload.md index 13b9e1fec..10a52ee03 100644 --- a/docs/dev/core/internal/payload.md +++ b/docs/dev/core/internal/payload.md @@ -74,21 +74,14 @@ A [Timing distribution](../../../user/metrics/timing_distribution.md) is represe | Field name | Type | Description | |---|---|---| -| `bucket_count` | Integer | The bucket count of the histogram. | -| `range` | Array<Integer> | The range indicated by its minimum and maxium value. | | `sum` | Integer | The sum of all recorded values. | -| `time_unit` | String | The timespan's time unit, see the [time distribution's configuration](../../../user/metrics/timing_distribution.md#configuration) for valid values. | | `values` | Map<String, Integer> | The values in each bucket. The key is the minimum value for the range of that bucket. Buckets with no values are not reported. | #### Example: ```json { - "bucket_count": 100, - "range": [0, 60000], - "histogram_type": "expontential", "sum": 3, - "time_unit": "milliseconds", "values": { "0": 1, "1": 3, diff --git a/docs/user/metrics/timing_distribution.md b/docs/user/metrics/timing_distribution.md index 040984beb..51cd8c752 100644 --- a/docs/user/metrics/timing_distribution.md +++ b/docs/user/metrics/timing_distribution.md @@ -2,34 +2,26 @@ Timing distributions are used to accumulate and store time measurement, for analyzing distributions of the timing data. -To measure the distribution of multiple timespans, see [Timing Distributions](timing_distribution.md). To record absolute times, see [Datetimes](datetime.md). +To measure the distribution of single timespans, see [Timespans](timespan.md). To record absolute times, see [Datetimes](datetime.md). + +Timing distributions are recorded in a histogram where the buckets have an exponential distribution, specifically with 8 buckets for every power of 2. +This makes them suitable for measuring timings on a number of time scales without any configuration. ## Configuration -Timing distributions have a required `time_unit` parameter to specify the resolution and range of the values that are recorded. The allowed values for `time_unit` are: - - - `nanosecond` - - `microsecond` - - `millisecond` - - `second` - - `minute` - - `hour` - - `day` - -Which range of values is recorded in detail depends on the `time_unit`, e.g. for milliseconds, all values greater 60000 are recorded as overflow values. - If you wanted to create a timing distribution to measure page load times, first you need to add an entry for it to the `metrics.yaml` file: ```YAML pages: page_load: type: timing_distribution - time_unit: millisecond description: > Counts how long each page takes to load ... ``` +> Note: Timing distributions have an optional `time_unit` parameter that is only used when samples are provided directly from an external tool in a unit other than nanoseconds. + ## API Now you can use the timing distribution from the application's code. @@ -74,7 +66,10 @@ assertEquals(2L, snapshot.count()) ## Limits -* Which range of values is recorded in detail depends on the `time_unit`, e.g. for milliseconds, all values greater 60000 are recorded as overflow values. +* Timings are recorded in nanoseconds. + On Android, the [SystemClock.getElapsedNanos()](https://developer.android.com/reference/android/os/SystemClock.html#elapsedRealtimeNanos()) function is used, so it is limited by the accuracy and performance of that timer. + +* The maxmimum timing value that will be recorded is 10 minutes. Longer times will be truncated to 10 minutes and an error will be recorded. ## Examples @@ -84,9 +79,8 @@ assertEquals(2L, snapshot.count()) * `invalid_value`: If recording a negative timespan. * `invalid_value`: If a non-existing/stopped timer is stopped again. +* `invalid_value`: If recording a time longer than 10 minutes. ## Reference * See [Kotlin API docs](../../../javadoc/glean/mozilla.telemetry.glean.private/-timing-distribution-metric-type/index.html) - -