[workers] Improve cron trigger/scheduled worker documentation

kristianfreeman commented 3 years ago

via Discord, we need to do a better job talking about scheduled workers in the docs. key parts I pulled from the message (also linked below):

First, there are no code samples that show it in use that I could find

Second, there is a major missing piece of information. It can take a LONG time until your job gets scheduled and actually starts to trigger

Third, when you make changes and wrangler publish them, it can take a long (forever?) time for that change to actually make it onto the server that executes the scheduled worker

https://discord.com/channels/595317990191398933/773306770893963264/859541328387768350

grempe commented 3 years ago

I'm the original poster, so I'd like to track this issue.

I'd also note that the debugging story for cron is a tough one. I can't seem to get any logging out of the cron execution. I have a job that I updated many hours ago (just to change the frequency and the destination URL that a post goes to) and....

Nothing...

I get nothing... Its being scheduled and run according to the UI event logging. But the destination is not showing any activity.

It doesn't get much simpler I think. Something wrong here? This was working, unchanged, but they only way I could tell was because I had it posting to a disposable endpoint at : https://ptsv2.com

[triggers]
crons = ["*/5 * * * *"]

const CRON_POST_URL = `https://api.github.com/repos/truestamp/observable-entropy/dispatches`

// there is an itty-router listening for fetch events specified elsewhere. This continues to work fine.
addEventListener('fetch', event => {
  event.respondWith(router.handle(event.request))
})

addEventListener('scheduled', event => {
  event.waitUntil(handleScheduled(event))
})

// See : https://mainawycliffe.dev/blog/github-actions-trigger-via-webhooks
async function handleScheduled(event) {
  await fetch(CRON_POST_URL, {
    method: 'POST',
    body: JSON.stringify({
      event_type: 'trigger_generate',
    }),
    headers: {
      Authorization: 'token ' + GITHUB_PAT,
      'Content-type': 'application/json; charset=UTF-8',
    },
  })
}

e0 commented 3 years ago

Second, there is a major missing piece of information. It can take a LONG time until your job gets scheduled and actually starts to trigger

I had a similar experience recently. I was trying to setup a daily cron job. For testing, this was set to start a few minutes after publishing the worker but there was no activity. Initially I thought I must have made a typo in my code but eventually I tested the scheduled event handler using "Quick edit -> Schedule -> Trigger scheduled event" and saw that it was able to trigger. After some more testing I could confirm that there was indeed a delay (around 30 minutes before the trigger).

The delay was something I had initially ruled out because under the "Past events" section for the worker, there was a message that goes something like "It can take up to 30 minutes for new or recently renamed workers to show up.". In my case, the worker was not new or recently renamed.

Some more observation about the delays:

I set up a cron job that runs every 2 minutes. After removing the cron job, it seemed like the original queue was not cancelled. So they still triggered every 2 minutes until about 30 minutes after removal. It also seems like the worker code state was stored along with the jobs in the queue. I had modified and published the worker but the change in behavior was not reflected in these delayed jobs.
The "Past events" section was still empty even when the delayed jobs started triggering. I would say it was an additional 30 minutes delay before past events showed up.

Relevant message I left on discord:

Albertozhao commented 3 years ago

@e0 I'll DM you on Discord to get more details because this sounds like a bug.

In the meantime, I'll update our documentation, so it mentions propagation time delays.

Albertozhao commented 3 years ago

Added a note about delays when making changes to your Cron Triggers: https://developers.cloudflare.com/workers/platform/cron-triggers

@grempe and @e0 thanks for reporting! The product team received your feedback and will scope in improvements for delays.

Also added a simple boilerplate for Cron Triggers that includes instructions for setting a Trigger in Wrangler (including with multiple environments): https://developers.cloudflare.com/workers/examples/cron-trigger

cloudflare / cloudflare-docs

[workers] Improve cron trigger/scheduled worker documentation #1695