1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
// 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 https://mozilla.org/MPL/2.0/.
use crate::metrics::DistributionData;
use crate::metrics::TimerId;
use crate::{ErrorType, TestGetValue};
use std::time::Duration;
/// A description for the [`TimingDistributionMetric`](crate::metrics::TimingDistributionMetric) type.
///
/// When changing this trait, make sure all the operations are
/// implemented in the related type in `../metrics/`.
pub trait TimingDistribution: TestGetValue<Output = DistributionData> {
/// Start tracking time for the provided metric.
/// Multiple timers can run simultaneously.
///
/// # Returns
///
/// A unique [`TimerId`] for the new timer.
fn start(&self) -> TimerId;
/// Stops tracking time for the provided metric and associated timer id.
///
/// Adds a count to the corresponding bucket in the timing distribution.
/// This will record an error if no [`start`](TimingDistribution::start) was
/// called.
///
/// # Arguments
///
/// * `id` - The [`TimerId`] to associate with this timing. This allows
/// for concurrent timing of events associated with different ids to the
/// same timespan metric.
fn stop_and_accumulate(&self, id: TimerId);
/// Aborts a previous [`start`](TimingDistribution::start) call. No
/// error is recorded if no [`start`](TimingDistribution::start) was
/// called.
///
/// # Arguments
///
/// * `id` - The [`TimerId`] to associate with this timing. This allows
/// for concurrent timing of events associated with different ids to the
/// same timing distribution metric.
fn cancel(&self, id: TimerId);
/// Accumulates the provided signed samples in the metric.
///
/// This is required so that the platform-specific code can provide us with
/// 64 bit signed integers if no `u64` comparable type is available. This
/// will take care of filtering and reporting errors for any provided negative
/// sample.
///
/// Please note that this assumes that the provided samples are already in
/// the "unit" declared by the instance of the metric type (e.g. if the
/// instance this method was called on is using [`crate::TimeUnit::Second`], then
/// `samples` are assumed to be in that unit).
///
/// # Arguments
///
/// * `samples` - The vector holding the samples to be recorded by the metric.
///
/// ## Notes
///
/// Discards any negative value in `samples` and report an [`ErrorType::InvalidValue`]
/// for each of them. Reports an [`ErrorType::InvalidOverflow`] error for samples that
/// are longer than `MAX_SAMPLE_TIME`.
fn accumulate_samples(&self, samples: Vec<i64>);
/// Accumulates precisely one signed sample in the metric.
///
/// Precludes the need for a collection in the most common use case.
///
/// Sign is required so that the platform-specific code can provide us with
/// a 64 bit signed integer if no `u64` comparable type is available. This
/// will take care of filtering and reporting errors for any provided negative
/// sample.
///
/// Please note that this assumes that the provided sample is already in
/// the "unit" declared by the instance of the metric type (e.g. if the
/// instance this method was called on is using [`crate::TimeUnit::Second`], then
/// `sample` is assumed to be in that unit).
///
/// # Arguments
///
/// * `sample` - The singular sample to be recorded by the metric.
///
/// ## Notes
///
/// Discards any negative value and reports an [`ErrorType::InvalidValue`].
/// Reports an [`ErrorType::InvalidOverflow`] error if the sample is longer than
/// `MAX_SAMPLE_TIME`.
fn accumulate_single_sample(&self, sample: i64);
/// Accumulates the provided samples in the metric.
///
/// # Arguments
///
/// * `samples` - A list of samples recorded by the metric.
/// Samples must be in nanoseconds.
/// ## Notes
///
/// Reports an [`ErrorType::InvalidOverflow`] error for samples that
/// are longer than `MAX_SAMPLE_TIME`.
fn accumulate_raw_samples_nanos(&self, samples: Vec<u64>);
/// Accumulates precisely one duration to the metric.
///
/// Like `TimingDistribution::accumulate_single_sample`, but for use when the
/// duration is:
///
/// * measured externally, or
/// * is in a unit different from the timing_distribution's internal TimeUnit.
///
/// # Arguments
///
/// * `duration` - The single duration to be recorded in the metric.
///
/// ## Notes
///
/// Reports an [`ErrorType::InvalidOverflow`] error if `duration` is longer than
/// `MAX_SAMPLE_TIME`.
///
/// The API client is responsible for ensuring that `duration` is derived from a
/// monotonic clock source that behaves consistently over computer sleep across
/// the application's platforms. Otherwise the resulting data may not share the same
/// guarantees that other `timing_distribution` metrics' data do.
fn accumulate_raw_duration(&self, duration: Duration);
/// **Exported for test purposes.**
///
/// Gets the number of recorded errors for the given error type.
///
/// # Arguments
///
/// * `error` - The type of error
///
/// # Returns
///
/// The number of errors recorded.
fn test_get_num_recorded_errors(&self, error: ErrorType) -> i32;
}