[ Documentation request ] Schedules: Add more details about phase

[mjameswh]

Brief description

The Schedules documentation mention that a schedule spec may be defined as "a simple interval, like "every 30 minutes" (aligned to start at the Unix epoch, and optionally including a phase offset)". The "alignment to Unix epoch" and "phase offset" concepts mentioned here are difficult to understand for some users, and it is non-obvious to most users how this phase parameter has to be calculated so that an interval spec fires exactly at a predetermined date and time (i.e. they are very likely to do this by trial and error).

We should provide some more explanation regarding these concepts, and add an example of how to calculate the phase based on a predetermined date and time.

Your recommended content

Extracted this from a recent Slack conversation. This needs some polishing, but I think the technical content and the example should be included in documentation.

Timestamps are measured in seconds (or actually, milliseconds, but let say seconds for simplicity) since January 1st 1970.

Now, 7 days is 604,800 seconds. 5 days is 432,000.

The schedule fires when the following holds:

((currentTimestampUTC - phase) % interval) == 0

So for example, using an interval of 7 days and a phase of 0, that equation holds on December 28th 2023, at midnight UTC:

((1703721600 - 0) % 604800) = 0

For an interval of 5 days and a phase of 0, it holds for December 29th 2023:

((1703808000 - 0) % 432000) = 0

User: What value would you recommend I use for phase so that it actually starts in 5 days or 7 days when that’s the value set ?

You will need to calculate that by yourself. Take the timestamp of any moment where you want your schedule to execute, then calculate the following:

referenceTimestampUTC % interval = phase

For example, if I want a schedule that will fire every 7 days, including Jan 1st 2024 at midnight UTC, I would do:

UNIX Timestamp of 2024-01-01T00:00:00 UTC => 1704067200
Interval of 7 days => 604800

phase = 1704067200 % 604800 => 345600

So I set my schedule interval to 604800s (7 days) and phase to 345600s (4 days), and I get:
(image showing upcoming schedule execution on Jan 1st, 2024, then Jan 8th...)

[antmendoza]

It would be nice to have this in the documentation