Glean - Cross-platform Telemetry library
source link: https://mozilla.github.io/glean/book/reference/metrics/timespan.html
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
Glean - Cross-platform Telemetry library
Timespan
Timespans are used to make a measurement of how much time is spent in a particular task.
To measure the distribution of multiple timespans, see Timing Distributions. To record absolute times, see Datetimes.
It is not recommended to use timespans in multiple threads,
since calling start
or stop
out of order will be recorded as an invalid_state
error.
Recording API
start
Starts tracking time. Uses an internal monotonic timer.
import org.mozilla.yourApplication.GleanMetrics.Auth
fun onShowLogin() {
Auth.loginTime.start()
// ...
}
Recorded errors
invalid_state
: If the metric is already tracking time (start
has already been called and notcancel
ed).
Limits
- The maximum resolution of the elapsed duration is limited by the clock used on each platform.
- This also determines the behavior of a timespan over sleep:
- On Android, the
SystemClock.elapsedRealtimeNanos()
function is used, so it is limited by the accuracy and performance of that timer. The time measurement includes time spent in sleep. - On iOS, the
mach_absolute_time
function is used, so it is limited by the accuracy and performance of that timer. The time measurement does not include time spent in sleep. - On Python 3.7 and later,
time.monotonic_ns()
is used. On earlier versions of Python,time.monotonics()
is used, which is not guaranteed to have nanosecond resolution. - On other platforms
time::precise_time_ns
is used, which uses a high-resolution performance counter in nanoseconds provided by the underlying platform.
- On Android, the
stop
Stops tracking time. The metric value is set to the elapsed time.
import org.mozilla.yourApplication.GleanMetrics.Auth
fun onLogin() {
Auth.loginTime.stop()
// ...
}
Recorded errors
invalid_state
: Callingstop
without callingstart
first.
cancel
Cancels a previous start
.
No error is recorded if there was no previous start
.
import org.mozilla.yourApplication.GleanMetrics.Auth
fun onLoginCancel() {
Auth.loginTime.cancel()
// ...
}
measure
Some languages support convenient auto timing of blocks of code.
measure
is treated as a start
and stop
pair for the purposes of error recording.
Exceptions (if present in the language) are treated as a cancel
.
import org.mozilla.yourApplication.GleanMetrics.Auth
Auth.loginTime.measure {
// Process login flow
}
setRawNanos
Explicitly sets the timespan's value.
Regardless of the time unit chosen for the metric, this API expects the raw value to be in nanoseconds.
Only use this if you have to
This API should only be used if the code being instrumented cannot make use of
start
,stop
, andcancel
ormeasure
. Time is hard, and this API can't help you with it.
import org.mozilla.yourApplication.GleanMetrics.Auth
fun afterLogin(loginElapsedNs: Long) {
Auth.loginTime.setRawNanos(loginElapsedNs)
// ...
}
Recorded errors
invalid_value
: If you attempt to record a negative elapsed duration.invalid_state
: If you call this API after callingstart
or call this API multiple times.
Testing API
testGetValue
Get the currently-stored value.
import org.mozilla.yourApplication.GleanMetrics.Auth
assertTrue(Auth.loginTime.testGetValue() > 0)
testHasValue
Test if the metric currently stores any value.
import org.mozilla.yourApplication.GleanMetrics.Auth
assertTrue(Auth.loginTime.testHasValue())
testGetNumRecordedErrors
Gets the number of errors recorded during operations on this metric.
import org.mozilla.yourApplication.GleanMetrics.Auth
assertEquals(1, Auth.loginTime.testGetNumRecordedErrors(ErrorType.InvalidValue))
Metric parameters
Example timespan metric definition:
auth:
login_time:
type: timespan
description: >
Measures the time spent logging in.
time_unit: millisecond
bugs:
- https://bugzilla.mozilla.org/show_bug.cgi?id=000000
data_reviews:
- https://bugzilla.mozilla.org/show_bug.cgi?id=000000#c3
notification_emails:
- [email protected]
expires: 2020-01-01
data_sensitivity:
- interaction
For a full reference on metrics parameters common to all metric types, refer to the metrics YAML registry format reference page.
Extra metric parameters
time_unit
Timespans have a required
time_unit
parameter to specify the smallest unit of resolution that the timespan will record.
The allowed values for time_unit
are:
nanosecond
microsecond
millisecond
second
minute
hour
day
Consider the resolution that is required by your metric, and use the largest possible value that will provide useful information so as to not leak too much fine-grained information from the client.
Values are truncated
It is important to note that the value sent in the ping is truncated down to the nearest unit. Therefore, a measurement of 500 nanoseconds will be truncated to 0 microseconds.
Data questions
- How long did it take for the user to log in?
Reference
Found a bug? Edit this file on GitHub.
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK