Closed Bug 1231769 Opened 6 years ago Closed 6 years ago

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

Categories

(Toolkit :: Telemetry, defect, P1)

defect
Points:
1

Tracking

()

RESOLVED FIXED
mozilla46
Tracking Status
firefox45 --- affected
firefox46 --- fixed

People

(Reporter: Dexter, Assigned: Dexter)

References

(Blocks 1 open bug)

Details

(Whiteboard: [measurement:client])

Attachments

(2 files, 5 obsolete files)

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
Blocks: 1201022
Points: --- → 1
Priority: -- → P1
Whiteboard: [measurement:client]
We should also provide stricter definitions for measurements types in simpleMeasurements/info (e.g. <number> to <unsinged integer>).
Assignee: nobody → alessio.placitelli
The activeTicks subsection is coming as a separate patch, so :chutten can take a look (maybe expand?) at it.
Attachment #8698031 - Flags: review?(gfritzsche)
Attached patch part 2 - activeTicks (obsolete) — Splinter Review
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.
Attachment #8698033 - Flags: feedback?(chutten)
Whoops, forgot to refresh.
Attachment #8698031 - Attachment is obsolete: true
Attachment #8698031 - Flags: review?(gfritzsche)
Attachment #8698041 - Flags: review?(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 :-(
Attachment #8698041 - Flags: review?(gfritzsche) → review+
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."
Attachment #8698033 - Flags: feedback?(chutten) → feedback-
Attached patch part 2 - activeTicks (obsolete) — Splinter Review
Thanks :chutten! I've updated the doc as suggested, and adding the note on subsession splits.
Attachment #8698033 - Attachment is obsolete: true
Attachment #8698561 - Flags: review?(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.
Attachment #8698561 - Flags: review?(gfritzsche)
Attached patch bug1231769_activeTicks.patch (obsolete) — Splinter Review
That should be it
Attachment #8698561 - Attachment is obsolete: true
Attachment #8698878 - Flags: review?(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 ..."
Attachment #8698878 - Flags: review?(gfritzsche) → review+
Attachment #8698878 - Attachment is obsolete: true
Attachment #8698890 - Flags: review+
Addressed the comments for totalTime/uptime.
Attachment #8698041 - Attachment is obsolete: true
Attachment #8698892 - Flags: review+
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
Status: NEW → ASSIGNED
https://hg.mozilla.org/mozilla-central/rev/8f1c046303f0
https://hg.mozilla.org/mozilla-central/rev/408ccf1d20c8
Status: ASSIGNED → RESOLVED
Closed: 6 years ago
Resolution: --- → FIXED
Target Milestone: --- → mozilla46
You need to log in before you can comment on or make changes to this bug.