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)

defect

Tracking

(Not tracked)

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?)

(I love this bug)

:wlach and Krupa'd probably have opinions on this.

Whiteboard: [telemetry:glean-rs:m?][docdays] → [telemetry:glean-rs:m17][docdays]

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.