1495685 - [meta] Document main ping sending behavior and semantics

Status: NEW

(Toolkit :: Telemetry, enhancement, P3)

Description

[Georg Fritzsche [:gfritzsche]]

Per a recent conversation in #fx-metrics slack, it's not entirely clear to everyone how things work.

The session documentation covers part of this:
https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/concepts/sessions.html

... but doesn't seem sufficient.
Specifically ping sender and other upload behavior are not explained in the same context.

We might need to add a more descriptive article, similar to the new profile articles on dtmo.

Comment 1

[Georg Fritzsche [:gfritzsche]]

Also, the first-shutdown ping, new-profile ping, update ping should be in this kind of overview.
Basically i think we need to describe the what and how of the mainline Telemetry.

Comment 2

[Chris H-C :chutten]

Georg, would you say that https://docs.telemetry.mozilla.org/datasets/pings.html (written via bug 1496775) completes the stated requirements in this bug?

Comment 3

[Georg Fritzsche [:gfritzsche]]

From my perspective that looks good.

Jesse, Su, do you have larger open questions from that?
If not right now, you can of course always reach out to us later.

Comment 4

[Jesse McCrosky]

Thanks for this :)  Very useful!  The only suggestion I'd make (optional, feel free to disregard and we can see if anyone asks for it in the future) is to provide a precise specification of the behavior instead of "it is around local midnight " (I believe it's sent a uniformly random time after random midnight between zero and some number of minutes?).  You never know when precise definitions will be needed.

Comment 5

[Chris H-C :chutten]

Well, if we want precision it's actually much more complicated than that :(

According to my reading of TelemetrySession, TelemetryController, and TelemetrySend:

A "daily" ping is due if 
1) We haven't sent a "daily" ping* since the previous midnight (because we would be sending more than one each day)
2) We haven't sent a "daily" ping* in the past 5min (because that would make the subsessions too short)

And 'sent a "daily" ping*' here means any of
a) sending a "daily" ping
b) the start of the Firefox session
c) sending an "environment-change" ping sent within 15min of midnight

If the user is active, every 5min we check to see if a "daily" ping is due. If the user is inactive, we only check every 60min. If we're due, we assemble the ping and _schedule_ the ping to be sent.

When scheduled pings are actually sent is another whole ball of wax. Generally we attempt to send immediately, but between local midnight and 1am we enter a blackout period of a uniformly-random duration for all pings, not just "daily" ones. And if at any time any pings we attempt to send fail we enter into an exponential backoff situation where we wait 1min, 2min, ... 120min before retrying until all pending pings in the batch successfully send.

In practice, it is unclear how these effects would combine to form any coherent timing behaviour of "daily" pings in an individual client or in a population. In some cases there won't be a "daily" ping at all. And sometimes it will be sent at a time wildly off from local midnight.

I'm not sure how to condense this information down into a timing statement that fits the doc, but maybe it's fit for recording somewhere else or on its own?

Comment 6

[Su-Young Hong]

Hi guy, 

Yea, this is awesome. Great work! 

I agree, the ping sending logic details should definitely be recorded *somewhere*. Probably not this document (maybe on it's own page?) but it would be useful to have somewhere. 

But overall, it looks great!

Comment 7

[Jesse McCrosky]

That is complicated ;)  Thanks for explaining.  I think that explanation itself is not bad.  I personally would include it as a subsection on that same page, but you could put it elsewhere and have a link on that page if you prefer.

Comment 8

[Chris H-C :chutten]

Okay, I think we'll put this with the other detailed documentation in the source docs. Probably in the "Submission" doc [1] which lives in Telemetry > Concepts.

Imma file a bug about this.

[1]: https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/concepts/submission.html