1231769 - Provide better documentation for "info" and "simpleMeasurements" sections of the main ping

Status: RESOLVED FIXED

(Toolkit :: Telemetry, defect, P1)

Description

[Alessio Placitelli [:Dexter]]

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

Comment 1

[Alessio Placitelli [:Dexter]]

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

Comment 2

[Alessio Placitelli [:Dexter]]

Attachment: part 1 - Expand the documentation for the main-ping

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

Comment 3

[Alessio Placitelli [:Dexter]]

Attachment: part 2 - activeTicks

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.

Comment 4

[Alessio Placitelli [:Dexter]]

Attachment: part 1 - Expand the documentation for the main-ping

Whoops, forgot to refresh.

Comment 5

[Georg Fritzsche [:gfritzsche]]

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 6

[Georg Fritzsche [:gfritzsche]]

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.

Comment 7

[Georg Fritzsche [:gfritzsche]]

(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 8

[Chris H-C :chutten]

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."

Comment 9

[Alessio Placitelli [:Dexter]]

Attachment: part 2 - activeTicks

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

Comment 10

[Georg Fritzsche [:gfritzsche]]

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.

Comment 11

[Alessio Placitelli [:Dexter]]

Attachment: bug1231769_activeTicks.patch

That should be it

Comment 12

[Georg Fritzsche [:gfritzsche]]

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 ..."

Comment 13

[Alessio Placitelli [:Dexter]]

Attachment: part 2 - activeTicks

Comment 14

[Alessio Placitelli [:Dexter]]

Attachment: part 1 - Expand the documentation for the main-ping

Addressed the comments for totalTime/uptime.

Comment 15

[Alessio Placitelli [:Dexter]]

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

Comment 16

[Carsten Book [:Tomcat]]

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