We should expand the documentation for the "info" and "simpleMeasurements" sections of the "main" ping in the in-tree docs [0]. [0] - https://gecko.readthedocs.org/en/latest/toolkit/components/telemetry/telemetry/main-ping.html

We should also provide stricter definitions for measurements types in simpleMeasurements/info (e.g. <number> to <unsinged integer>).

The activeTicks subsection is coming as a separate patch, so :chutten can take a look (maybe expand?) at it.

Chris, since you deep dived into activeTicks, would you mind checking if the documentation still holds... and maybe expand with what you've found? :-) I took that straight off the FHR docs.

Whoops, forgot to refresh.

Comment on attachment 8698041 [details] [diff] [review] part 1 - Expand the documentation for the main-ping Review of attachment 8698041 [details] [diff] [review]: ----------------------------------------------------------------- ::: toolkit/components/telemetry/docs/main-ping.rst @@ +88,5 @@ > +This section contains a list of simple measurements, or counters. In addition to the ones highlighted below, Telemetry timestamps (see `here <https://dxr.mozilla.org/mozilla-central/search?q=%22TelemetryTimestamps.add%22&redirect=false&case=true>`_ and `here <https://dxr.mozilla.org/mozilla-central/search?q=%22recordTimestamp%22&redirect=false&case=true>`_) can be reported. > + > +totalTime > +~~~~~~~~~ > +An integer representing the number of seconds the session has been alive. Is this monotonic or not? @@ +92,5 @@ > +An integer representing the number of seconds the session has been alive. > + > +uptime > +~~~~~~ > +An integer representing the number of minutes the session has been alive. Is this monotonic or not? Also, super redundant measurement :-(

Comment on attachment 8698033 [details] [diff] [review] part 2 - activeTicks Review of attachment 8698033 [details] [diff] [review]: ----------------------------------------------------------------- ::: toolkit/components/telemetry/docs/main-ping.rst @@ +155,5 @@ > Integer count of the number of pings that need to be sent. > > +activeTicks > +~~~~~~~~~~~ > +Integer count of ticks the session was active for. Gecko periodically sends out a signal when the session is active. Session activity involves keyboard or mouse interaction with the application. Each tick represents a window of 5 seconds where there was interaction. I think this needs a bit more detail if we can spec this out: * is this dependent on foreground window state or not? * is this for all keyboard & mouse events? * if not, which events specifically? Chris, can you maybe add some more precise details? This would be pretty important background for building on this measurement.

(In reply to Georg Fritzsche [:gfritzsche] [away Dec 19 - Jan 3] from comment #6) > ::: toolkit/components/telemetry/docs/main-ping.rst > @@ +155,5 @@ > > Integer count of the number of pings that need to be sent. > > > > +activeTicks > > +~~~~~~~~~~~ Let's also point out the differences for subsession/main and saved-session pings for this and the other measurements.

Comment on attachment 8698033 [details] [diff] [review] part 2 - activeTicks Review of attachment 8698033 [details] [diff] [review]: ----------------------------------------------------------------- activeTicks is an odd measurement, and is probably best used for measuring trends (now that it's a bit less volatile). It won't give you a "for-sure, this user was looking at or expecting things from the browser" kind of measurement, because that's impossible without eye-tracking and mind-reading. But it will tell you when the user was actually interacting with the browser. ::: toolkit/components/telemetry/docs/main-ping.rst @@ +155,5 @@ > Integer count of the number of pings that need to be sent. > > +activeTicks > +~~~~~~~~~~~ > +Integer count of ticks the session was active for. Gecko periodically sends out a signal when the session is active. Session activity involves keyboard or mouse interaction with the application. Each tick represents a window of 5 seconds where there was interaction. activeTicks is a count of each five-second window (NS_USER_INTERACTION_INTERVAL) the user was considered "active". Plus one for the extra one we fire immediately when the user becomes active after being inactive. This is for some mouse and gamepad events, and all touch, keyboard, wheel, and pointer events. (see EventStateManager::PreHandleEvent) It does not take into account whether or not the window has focus or is in the foreground. Just if it is receiving these interaction events. To put this in English as a documentation thing: "activeTicks is an integer count of the number of five-second intervals ('ticks') the user was considered 'active' (sending UI events to the window). This might be useful to give a trend of how much a user actually interacts with the browser when compared to overall session duration."

Thanks :chutten! I've updated the doc as suggested, and adding the note on subsession splits.

Comment on attachment 8698561 [details] [diff] [review] part 2 - activeTicks Review of attachment 8698561 [details] [diff] [review]: ----------------------------------------------------------------- Can you please add the other details from comment 8 here? This will be very useful information.

That should be it

Comment on attachment 8698878 [details] [diff] [review] bug1231769_activeTicks.patch Review of attachment 8698878 [details] [diff] [review]: ----------------------------------------------------------------- ::: toolkit/components/telemetry/docs/main-ping.rst @@ +155,5 @@ > Integer count of the number of pings that need to be sent. > > +activeTicks > +~~~~~~~~~~~ > +Integer count of the number of five-second intervals ('ticks') the user was considered 'active' (sending UI events to the window). Plus one for the extra one we fire immediately when the user becomes active after being inactive. This is for some mouse and gamepad events, and all touch, keyboard, wheel, and pointer events (see `EventStateManager.cpp <https://dxr.mozilla.org/mozilla-central/rev/e6463ae7eda2775bc84593bb4a0742940bb87379/dom/events/EventStateManager.cpp#549>`_). Nit: The "Plus one" is missing context? Instead we could go for "An extra event is fired immediately ..."

Addressed the comments for totalTime/uptime.

https://hg.mozilla.org/integration/fx-team/rev/8f1c046303f0e1d1ffe8f5c59fa96b8c36ac5f3b Bug 1231769 - Provide better documentation for "info" and "simpleMeasurements" sections of the main ping. r=gfritzsche https://hg.mozilla.org/integration/fx-team/rev/408ccf1d20c8c7faecbf0fb256d0463922250865 Bug 1231769 - Add the documentation for activeTicks. r=gfritzsche

https://hg.mozilla.org/mozilla-central/rev/8f1c046303f0 https://hg.mozilla.org/mozilla-central/rev/408ccf1d20c8