How to debug WHMCS cron job activity

[Remitur]

I've recently had to investigate one of those slightly annoying WHMCS problems: the cron job appears to be running correctly, but some executions never actually finish.

This can be surprisingly easy to miss.

Having cron.php started every 5 minutes only tells us that cron is starting it every 5 minutes. It doesn't tell us whether the previous execution actually completed. If an automation task hangs — because of an external API, a registrar/module, a network problem, a database issue, custom code, etc. — you may eventually end up with several overlapping cron.php processes without immediately noticing what is going on.

I put together a debugging approach that gives visibility into three different levels:

• whether the PHP cron process actually starts and terminates;

• whether the WHMCS automation cycle enters and exits normally;

• which individual WHMCS automation task starts but never returns (or simply takes an unusually long time).

The basic idea is to use the PreCronJob / AfterCronJob and PreAutomationTask / PostAutomationTask hooks, combined with a simple external shell wrapper and a check for overlapping processes.

Instead of just knowing:

"The WHMCS cron seems to get stuck sometimes."

you can hopefully get to something much more useful, such as:

cron.php started
DomainSync started
another cron.php process started
another cron.php process started
DomainSync never returned

At that point, at least you know where to start looking.

I've written up the complete procedure, including the hooks, shell script, logging examples and some additional notes here:

https://eurossl.eu/knowledgebase/whmcs-cron-job-stuck-debugging/

I'm posting this because I'd still like to contribute useful technical information back to the WHMCS community.

However, after fighting over the years with the community's occasionally ("creative" code editor, formatting issues, disappearing posts and similar adventures), I've decided to keep the full article and code somewhere I can actually maintain them. 🙂

Hopefully this will save someone a few hours of debugging.