Queue Health and Tools #
Requires Preferred license. Applies to PetMatchPro 8.7.0 and later.
This article covers the operational instruments PetMatchPro provides to keep an eye on the analytics pipeline: the Queue Health card on the Analytics tab, and the Flush Queue Now and Run Cron Self-Test buttons on the Tools tab.
The Queue Health Card #
Find it under PetMatchPro > Analytics > Analytics Queue Health. The card shows three rows:
| Row | What It Shows | What “Healthy” Looks Like |
|---|---|---|
| Queue Depth | Number of impression entries currently buffered, waiting on the next cron flush | Anywhere from 0 to a few hundred is normal during active traffic. Should drop to 0 within 60 seconds of activity ending. |
| Last Flush | How long ago the cron task last drained real impression data into the analytics database. This timestamp tracks data freshness, not cron activity – on a site with no recent visitor traffic the cron is still running every minute on an empty queue, but “Last Flush” continues showing the age of the last real drain. “Never” appears on a brand-new install or immediately after Clear All Data, until the first impression batch is committed. | Under 60 seconds during active traffic. “Never” on a fresh install is fine. Any age (even hours) is fine on a low-traffic site as long as no warning badge appears next to it. |
| Next Scheduled | When the cron task is set to fire next | A time under 60 seconds in the future. |
Refresh Button #
Below the three rows is a Refresh button that re-pulls current health metrics in place without reloading the entire admin page. Useful when monitoring the pipeline during active traffic – click Refresh every few seconds to watch Queue Depth grow as impressions arrive, then drop to 0 when the next 1-minute cron tick drains them.
Refresh works in both Queue Health locations: the Analytics tab card and the Tools tab Analytics Queue accordion. The Tools-tab Flush Queue Now button automatically triggers a Refresh after a successful flush, so depth and last-flush values update without a manual click.
Warning States #
The yellow “Cron may be broken” badge appears when PetMatchPro detects the WP-Cron handler has not run in more than 5 minutes – the same threshold that triggers the synchronous-flush safety fallback. Two scenarios produce the badge:
- On “Next Scheduled” – No future cron event is registered for the analytics flush hook. Usually a plugin conflict that unscheduled the event, or WP-Cron is disabled at the host level without a real cron-job replacement.
- On “Last Flush” – The cron handler itself has not fired in over 5 minutes. (Note: this is a separate signal from the “Last Flush” timestamp’s age – the badge is gated on the last cron tick, not the last data flush. So a low-traffic site with cron firing fine on empty queues will show an old “Last Flush” age but NO badge – that is healthy. Conversely, on a busy site with broken cron, the queue accumulates and the badge appears alongside whatever the last real-flush age was.)
If you see either badge, see the WP-Cron requirement guide.
Flush Queue Now Button #
Found at PetMatchPro > Tools > Analytics Queue. Click the button to drain the queue immediately, without waiting for the next scheduled cron tick.
When to use it #
- After a content change. You just published a batch of new animals and want the dashboard to reflect impressions on them right away rather than waiting up to 60 seconds.
- Before exporting analytics data. Drain the queue first so the export captures everything currently buffered.
- While diagnosing a sync issue. A successful manual flush rules out a coding problem – if the manual button works but cron does not, the issue is with WP-Cron, not PetMatchPro.
What it shows #
After clicking, the button reports the number of rows drained as a green badge (“Flushed N rows.”). It then automatically triggers a full Queue Health refresh, so all three rows (Queue Depth, Last Flush, Next Scheduled) update in place to reflect the post-flush state – depth drops to 0, Last Flush updates to “just now”, and any “Cron may be broken” badge clears if the flush brought staleness back below threshold. If the flush fails, you will see a red “Flush failed.” badge; check your error log for the actual cause.
Run Cron Self-Test Button #
Found at PetMatchPro > Tools > Cron Self-Test. This is an active diagnostic that confirms WP-Cron is actually firing on your site, regardless of what the Queue Health card says.
How it works #
- You click “Run Cron Self-Test”.
- PetMatchPro schedules a single one-shot WP-Cron event 60 seconds in the future.
- The page polls every 5 seconds for up to 2 minutes.
- If the test event fires within the deadline: green “Cron is healthy” badge.
- If the deadline elapses without the event firing: yellow “Cron does not appear to be firing” warning, with a link to the cron requirement KB article.
The test runs independently of the analytics queue, so a “healthy” result confirms cron itself is working – any analytics issue is elsewhere. A “failing” result means WP-Cron needs attention before analytics can recover.
When to run it #
- Right after enabling tracking on a new install, to confirm the pipeline works.
- If the dashboard shows zero new impressions despite real traffic.
- If the Queue Health card shows a “Cron may be broken” badge and you want to confirm before contacting your host.
- After upgrading WordPress, PetMatchPro, or any caching/security plugin, to confirm nothing broke cron.
Rebuild Daily Summaries Button #
Found at PetMatchPro > Tools > Rebuild Daily Summaries. Clicking the button re-aggregates raw analytics events into the daily summary table that powers the dashboard.
Why this exists #
The dashboard reads from a daily summary table – one row per (date, event type, method, animal, species, source, action type) combination – instead of GROUPing the raw events table on every render. A 5-minute cron and a nightly 3 AM finalize keep the summary current automatically. The Rebuild button is for the cases where the cron has not had a chance to run yet:
- Right after upgrading to 8.7.0. The summary table starts empty; this button backfills it from your existing raw event data so the dashboard has data to display.
- After a database restore. If you restore a backup that has raw events but stale (or missing) summary rows, click Rebuild to bring them into sync.
- While diagnosing dashboard issues. If the dashboard shows zero data despite raw events being present, Rebuild rules out a stale summary table.
What it does #
- Finds raw-event dates not yet present in the summary table, oldest first.
- Processes up to 90 days per click (capped to keep the request fast).
- Refreshes today’s summary in addition to the historical backfill so the dashboard reflects the latest activity immediately.
- Reports the number of days processed and rows written.
If your analytics history is longer than 90 days and you need to backfill the entire range, click the button repeatedly – each click picks up where the previous one left off.
What These Tools Do Not Do #
- They do not edit your wp-config.php. If WP-Cron is fully disabled at the host level, the tools can detect it but cannot fix it. You (or your host) must add a real cron job. See cron requirement.
- They do not auto-refresh. The Queue Health card reflects state at the time of the page load. Reload the Analytics tab to see fresh numbers.
- They do not require Preferred license to view, but do require
manage_optionscapability to act. Editor-role users will not see the buttons.
Next Steps #
- WP-Cron Requirement – Setting up real cron when the self-test fails
- Understanding PMP Analytics – The metrics this queue feeds
- Interpreting Position Impact – Reading the dwell-gated position data
