Open
Bug 1703581
Opened 4 years ago
Updated 4 years ago
Consider documenting what a good "Description" is for Metrics and Pings
Categories
(Data Platform and Tools :: Glean: SDK, defect, P3)
Data Platform and Tools
Glean: SDK
Tracking
(Not tracked)
NEW
People
(Reporter: chutten, Unassigned)
Details
(Whiteboard: [telemetry:glean-rs:m17][docdays])
I went looking for guides for what to include in a Metric's or Ping's description and couldn't find any.
Off the top of my head
- Metrics with enumerable values (like boolean) enumerate what conditions result in each of the enumerable values. (Like "True if we failed to register with the idle service. Absent otherwise. Means IPC probably isn't working well. Child-process data will likely be absent, or incomplete". (from
fog.failed_idle_registration
)) - Labeled metrics should describe what the labels mean (ideally supported by the static list of labels in the
labels
field). Are these from another library? How many are there? - Metrics should describe specific information about what values mean. Is higher better?
- For pings it'd be helpful to know if its presence or absence is the sign of a problem?
- Metrics and Pings both should describe their Purpose: Is this supporting a business thing? A perf thing? Monitoring? Is this meant to be looked at by humans or by machines?
- Pings should include their timing and any configuration or population filters that would prevent this one specifically from being sent. (ie, is it Windows-only? Do users have to flip a pref? Is this sent on every startup? How long after process start?)
Comment 1•4 years ago
|
||
(I love this bug)
Reporter | ||
Comment 2•4 years ago
|
||
:wlach and Krupa'd probably have opinions on this.
Updated•4 years ago
|
Whiteboard: [telemetry:glean-rs:m?][docdays] → [telemetry:glean-rs:m17][docdays]
Comment 3•4 years ago
|
||
Most of those sound pretty good. Some examples of pings and metrics which do a good job here would be useful. With metric annotations, getting things 100% complete and perfect in the original metric description will hopefully be a little less important. In that context, I'd probably suggest not over-rotating on purpose: one or two sentences (maybe cribbed from the data review) is probably fine.
You need to log in
before you can comment on or make changes to this bug.
Description
•