---
title: 12.08 Monitoring Background Tasks
description: The Queue Monitor shows every background task SimpleRisk has queued, live, along with the health of the two workers that run them. This article covers…
---
[Skip to content](https://support.simplerisk.com/kb/12-08-monitoring-background-tasks#main-content)
English
Show submenu for translations
[Customer portal](https://support.simplerisk.com/tickets?hsLang=en)
[](https://www.simplerisk.com/)
Open main navigation
Close main navigation
- English
Show submenu for translations
- [Customer portal](https://support.simplerisk.com/tickets)
- [Contact us](https://www.simplerisk.com/about-us/contact-us)
[Contact us](https://www.simplerisk.com/about-us/contact-us)
How can we help you?
- There are no suggestions because the search field is empty.
1. [SimpleRisk Knowledge Base](https://support.simplerisk.com/kb?hsLang=en)
2. [Administrator Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en)
3. [12 Operations](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#12-operations)
# 12.08 Monitoring Background Tasks
## The Queue Monitor shows every background task SimpleRisk has queued, live, along with the health of the two workers that run them. This article covers reading the page, finding out why a task failed, stopping, canceling, running early or restarting tasks one at a time or in bulk, deleting finished tasks in bulk, the admin notification for failed tasks, and how long finished tasks are kept.
## Why this matters
A lot of what SimpleRisk does happens after the page you clicked has already finished loading. Queued email, workflow runs, AI requests, compliance audit initiation, asset discovery, the ComplianceForge SCF framework import and the daily cleanup jobs all run as background tasks, picked up by a worker process that cron keeps alive. When one of them breaks, nobody sees an error on screen. The email just doesn't arrive, or the framework just doesn't finish loading.
The Queue Monitor is where you find out what's actually going on. It answers four questions without making you leave the page: what's running, what's waiting, what's failing and why, and whether the workers are alive at all. We rebuilt it after the SCF Extra's import started failing when the SCF project changed its workbook format. Finding the cause back then meant opening a modal of every step in the task, spotting the failed one by eye, and reading raw JSON to get at the error. Now the failed step and its error are the first thing you see when you expand the row.
## Before you start
- **Admin access.** The Queue Monitor page, its Settings Hub tile, and the matching API endpoints are restricted to administrators.
- **The cron workers scheduled.** The page shows what the workers are doing. It can't run tasks itself. If you haven't scheduled `cron_queue_worker.php`, `cron_promise_worker.php` and `cron_queue_loader.php`, see [The Cron Jobs](https://support.simplerisk.com/kb/02-07-the-cron-jobs?hsLang=en) first. The loader is the one that queues scheduled work such as the daily cleanup, and the health strip doesn't watch it.
## Opening the Queue Monitor
Click the **Settings cog** in the page header to open the Settings Hub, then click the **Queue Monitor** tile in the System category. The page lives at `/admin/queue_monitor.php`.
You don't need to refresh it. The list, the counts and the worker strip update every five seconds, and the indicator beside the title reads **Live · updated 3s ago** or similar. Updates pause while the browser tab is hidden and catch up as soon as you come back to it. If an update fails, the indicator turns red and reads **Update failed · retrying in 20s**; the table you were looking at stays put, and the page keeps retrying on its own, waiting a little longer each time, up to a minute between attempts. If your session ends while the page is open, a notice asks you to refresh and sign in again.
### The worker health strip
The strip under the toolbar is the first thing to look at when tasks seem stuck.
- **Queue worker** is the process that picks up tasks and runs them (`cron_queue_worker.php`).
- **Step worker** advances the individual steps of multi-step tasks (`cron_promise_worker.php`).
- **Oldest pending** is how long the longest-waiting task has been in the queue.
- **Failed in the last 24 hours** counts tasks that ended in failure in the past day. It's highlighted when it isn't zero.
Each worker reads **Running** or **Not running**. A worker counts as not running once it has gone about three minutes without recording a heartbeat, and a stopped worker shows its last heartbeat right in the strip (**Last heartbeat 2h ago**, or **No heartbeat recorded** if it never reported one). If the page can't read worker status at all, the strip shows **Worker status unavailable** instead.
When `config.php` allows more than one worker of a kind (see [Running more than one worker](https://support.simplerisk.com/kb/02-07-the-cron-jobs#running-more-than-one-worker)), the pill also counts them, for example **Queue worker · Running · 2 of 3**. It turns amber while some but not all of them are counted as running. Right after the number is raised that's expected. With the `cron.php` orchestrator run every minute, as recommended, the extra workers start within a minute or two; with a separate cron line per worker script they start one per run of that line. A worker also drops out of the count while it's busy with something long, because it only checks in between pieces of work: a queue worker around each task, a step worker after each batch of steps (up to 20 by default). So a pill that flickers amber while long tasks run is normal. If it stays amber while nothing long is running, the missing workers can't start; check the host's memory and the database's connection limit. With the default of one worker the pill reads exactly as described above.
A stopped worker is almost always a cron problem rather than a SimpleRisk one: the cron entry is missing, the cron daemon is down, or the worker is failing on startup. Work through the cron section of [Troubleshooting Common Issues](https://support.simplerisk.com/kb/12-04-troubleshooting-common-issues#issue-3-cron-jobs-arent-firing).
### What each status means
Every task carries one status chip:
- **Pending** — waiting for a worker to pick it up.
- **Running** — a worker is executing it.
- **Retrying** — the last attempt failed and the task is waiting for its next one. The chip names the attempt and counts down to it, for example **Retrying · #2 in 28s**. A running task whose current step is being retried also shows **Retrying**, without the countdown, but it's still counted and listed under the **Running** pill, not **Retrying**.
- **Stopping…** — someone stopped or canceled the task while a step was in flight. The step is finishing; nothing after it will start.
- **Completed** — finished successfully.
- **Failed** — used up its retries, failed in a way that can't be retried, or kept stopping part-way. A task or step that stops without finishing, because its worker crashed, ran out of memory, was killed or lost its database connection, goes back in the queue on its own, but only a limited number of times (five by default; see [Tuning the workers](https://support.simplerisk.com/kb/02-07-the-cron-jobs#tuning-the-workers)). After that it's marked failed, so you get the failed-task notification instead of the task being started over and over.
- **Canceled** — stopped or canceled before it finished.
A task that was restarted also carries **Restarted as task #{new-id}** under its chip, so you can follow it to the new copy.
### Priority
The **Priority** chip shows which tier the task's priority number falls in. Workers pick higher-priority tasks first.
- **Immediate:** 100 and above
- **High:** 75–99
- **Medium:** 50–74
- **Low:** 25–49
- **Lowest:** below 25
Hover a chip to see the exact number.
### The columns
The list shows **ID**, **Task** (the task type, such as `core_email_send`), **Status**, **Progress** (for example **3 of 6 steps** on a multi-step task), **Attempts**, **Priority**, **Queued** and **Duration**. Duration appears only on finished tasks. It measures from the moment the task was queued to the moment it finished, so it includes any time the task spent waiting for a worker, not just the time it took to run. ID, Task, Status, Attempts, Priority and Queued sort when you click their headers.
## Step-by-step: finding out why a task failed
1. **Narrow the list.** Click the **Failed** status pill. Each pill (**All**, **Pending**, **Running**, **Retrying**, **Completed**, **Failed**, **Canceled**) shows how many tasks it holds. To narrow further, type into **Search task type, ID or error text**, pick a type from the **All types** dropdown, or set the **From** and **to** dates, which filter on the date each task was queued and include the whole end day. If nothing matches, **Clear filters** resets everything.
The status filter is part of the page address, so `/admin/queue_monitor.php?status=failed` opens straight to the failed tasks. That's the link the failure notification uses, and it's worth bookmarking.
1. **Expand the task.** Click the caret at the start of the row. For a failed task, a red banner at the top of the expansion names where it broke (**Failed at step 4, "{step name}"**, or **Last error** for a task without steps), followed by the error text itself, how many attempts it made, and when it last tried.
2. **Read the step table.** Under the banner, the task's steps are listed in the order they run, with **Step**, **Status**, **Time** and **Note** columns. The failing step is highlighted and carries its error in the Note column. Steps after it read **Not run**.
Some tasks show **Step details are not available for this task.** instead. That's normal for task types that run as a single step, which never record steps at all. It's also what you'll see on an older task: the details of finished steps are cleared after seven days (the `PROMISES_PURGE_RETENTION_DAYS` setting), even though the task itself stays in the list longer.
1. **Look at the payload if you need to.** **View payload** opens the data the task was queued with, which is often where the useful context is: for a queued email, the recipient, subject and body. Values stored under keys that look like secrets (passwords, tokens, API keys and similar) are shown as `[redacted]`. Redaction goes by the key's name, not its content, so treat the payload as sensitive anyway.
2. **Fix the cause, then act on the task.** Restart it, or leave it as a record. The next section covers what each action does.
## Acting on a task
Hover over a row (or tab into it) and the actions it allows appear at the right-hand end. On a narrow screen or a touch device they fold into the row's **⋯** menu. Every action asks you to confirm first, and the confirmation says exactly what will happen.
- **Running:** **Stop**
- **Pending or Retrying (waiting):** **Run Now**, **Cancel**
- **Failed or Canceled:** **Restart**
- **Completed:** none
Deleting isn't a row action. It's done from the bulk bar, covered in [Deleting finished tasks](https://support.simplerisk.com/kb/12-08-monitoring-background-tasks#deleting-finished-tasks).
**Stop** is cooperative. The step in progress finishes first, nothing after it starts, and the task then shows as **Canceled**. Until the step finishes the row reads **Stopping…**. Steps that already finished aren't rolled back.
**Cancel** removes a waiting task from the queue. It won't run. If some of its steps had already finished on an earlier attempt, they aren't undone.
**Run Now** moves a waiting task to the front of the queue: it gets **Immediate** priority and any retry wait is cleared, so the next worker pass picks it up. It doesn't run the task inside your browser request, and it's never offered on a task that's already running, so it can't interrupt anything.
**Restart** doesn't revive the failed task. It queues a new task of the same type, with the same payload, starting again from step 1, at the priority the original was first queued with. The original stays in the list as history, marked **Restarted as task #{new-id}**, and the new task records where it came from. You can restart a task only once. A task that's still **Stopping…** can't be restarted until its in-flight step ends. A task a worker is still running can't be restarted either, even when it already reads **Canceled** (a cancel doesn't interrupt a running task); it's reported as still stopping. Wait for it to finish and try again.
Restart and Run Now both warn that the task will run, side effects such as sending email included. Take that literally. A restarted email task sends its email. If the queue worker isn't running when you confirm, the dialog tells you, because the task will sit there until the worker comes back.
After you confirm, a message reports how many tasks the action applied to and how many it skipped, with a reason for each skip (the task's state changed since the page last updated, the task no longer exists, the task type doesn't allow it). Each applied action is written to the audit trail.
### Tasks you can't act on
Some task types are deliberately off-limits:
- **Encrypted Database Extra tasks** (task types beginning with `encryption_`) offer no actions at all, and can't be deleted. That Extra manages its own activation, deactivation and recovery flow, and the monitor stays out of it. See [Enabling Encryption](https://support.simplerisk.com/kb/09-02-enabling-encryption?hsLang=en).
- **Workflow tasks** (`core_workflow_execute`, `core_workflow_action_execute`) can't be restarted. Some of a workflow's actions may already have fired, and replaying the run would fire them again. For the same reason they're never retried automatically: the first error fails the task, marks the workflow run or step failed, and sends the failed-task notification.
- **ComplianceForge SCF install and uninstall tasks** (`scf_install_and_upgrade`, `scf_uninstall`) can't be restarted. The SCF Extra decides when those run; a blind restart could reinstall the framework after an uninstall.
- **AI document-processing chunks** (`ai_document_to_control_chunk_process`) can't be restarted, because the working data they point at is cleaned up as each chunk finishes, and the document text they share is cleaned up once the last chunk of that document is done.
- **AI risk analysis tasks** (`ai_risk_fair_analyze`) can't be deleted. The AI Extra reads their history to decide whether a risk needs analysing again and to stop retrying a risk that keeps failing. Without the finished tasks, every risk looks as if it had never been analysed, and the Extra would analyse them all again, paying for the AI calls a second time. The daily retention cleanup keeps them for the same reason.
These tasks can still be stopped or canceled, except the Encrypted Database ones.
## Acting on many tasks at once
1. **Pick a status pill first.** Bulk actions depend on the view. **Pending**, **Running** and **Retrying** offer **Cancel selected**; **Failed** and **Canceled** offer **Restart selected** and **Delete selected**; **Completed** offers **Delete selected**. Under **All** there's no bulk action, because the view mixes states, and the bar says **Choose a status filter to act on the selected tasks.**
2. **Tick the tasks.** Ticking a row swaps the toolbar for a bulk bar that counts your selection. The header checkbox selects every row on the current page. Changing a filter clears the selection. Paging and sorting don't, so the count in the bar (and in the confirmation) can include ticked rows that are no longer on screen. Check the number before you confirm.
3. **Widen to every match if you need to.** Once every row on the page is ticked and more tasks match the filter, a **Select all {N} matching tasks** link appears. The action then covers the tasks that matched when the count was taken; anything queued after that isn't swept in. In the **Failed** and **Canceled** views, which offer both Restart and Delete, the link counts every matching task, and each confirmation names how many of them that action will actually reach (a task that was already restarted isn't restarted again, for example).
4. **Confirm.** One action covers at most 500 tasks, counted per action. If an action would reach more, its button is disabled; if every action would, the bar says so and asks you to narrow the filter. A bulk cancel cancels waiting tasks at once and lets running ones finish their current step before stopping. A bulk restart warns that the tasks will run again, side effects and all, and skips any task that was already restarted or whose type can't be restarted.
### Deleting finished tasks
**Delete selected** removes completed, failed and canceled tasks from the queue for good, together with their step details. Nothing is archived, and the tasks don't come back. The confirmation names how many tasks you're about to delete and says the deletion can't be undone; it opens with the focus on **Back**, and pressing Esc won't dismiss it, so a stray keystroke can't commit the delete. Each deleted task gets an entry in the audit trail, which is the only record of it once it's gone.
Pending and running tasks can't be deleted by any route, including **Select all {N} matching tasks**. A few finished tasks are skipped too, and the result message counts them:
- Tasks of the Encrypted Database Extra and AI risk analysis tasks, for the reasons in [Tasks you can't act on](https://support.simplerisk.com/kb/12-08-monitoring-background-tasks#tasks-you-cant-act-on). When you use **Select all {N} matching tasks**, they aren't included in the number the confirmation names.
- A canceled task that's still **Stopping…**, any finished task that still has a step in progress, and any task a worker is still running right now (a cancel doesn't interrupt a running task). Deleting it then would pull the records out from under work that's still writing to them. These are reported as still stopping. Wait for the work to end and try again.
- A task canceled recently, even when it already reads **Canceled**. "Recently" means within the stuck-task window, which is at least half an hour (half an hour by default; see [Tuning the workers](https://support.simplerisk.com/kb/02-07-the-cron-jobs#tuning-the-workers)). Its worker may still be setting up the steps it was about to run, so the delete waits until the cancel has settled; it's reported as still stopping until then.
Deleting a task that was restarted doesn't affect the new copy. If you delete the new copy, the original keeps its **Restarted as task #{new-id}** note pointing at a task that no longer exists, and it still can't be restarted a second time.
You rarely need this. The daily retention cleanup (see [How long finished tasks are kept](https://support.simplerisk.com/kb/12-08-monitoring-background-tasks#how-long-finished-tasks-are-kept)) deletes old finished tasks by age on its own. **Delete selected** is for clearing a batch now: a few hundred failures from a mail outage you've already fixed and don't want crowding the **Failed** view, or test tasks someone queued by mistake.
## The failed-task notification
When a background task fails for good, SimpleRisk sends every admin a notification titled **A background task failed**. It names the task type and, when the instance's base URL is set, links to the Queue Monitor already filtered to failed tasks. A task that's still retrying doesn't trigger it, and neither does one someone canceled.
To keep a systemic fault from burying the notification center, you get at most one notification per task type per hour. If one fault fails three hundred tasks of the same type in an hour, you get one notification, not three hundred, so open the monitor to see the real scale. Queued email (`core_email_send`) is the exception: it already raises its own **Email Delivery Failed** notification, covered in [Troubleshooting Common Issues](https://support.simplerisk.com/kb/12-04-troubleshooting-common-issues#issue-5-notifications-not-arriving), and isn't notified twice. The notification expires on the same schedule as email delivery failures, set by **Email Delivery Failure Notification Retention** on the **Mail** settings page.
## How long finished tasks are kept
Click **Task retention** in the toolbar to set how long finished tasks stay in the list.
- **Completed and canceled tasks (days)** — default 30.
- **Failed tasks (days)** — default 90.
Enter any whole number from 0 to 3650. Zero keeps tasks forever. A cleanup task runs once a day and deletes finished tasks older than these limits, together with any step details they still have. Pending and running tasks are never deleted, however old they are. The cleanup works in short batches, so the first run after you shorten a limit on a large, long-neglected queue may take a few days to catch up. You'll see the cleanup itself in the list as `core_queue_purge`. If it never shows up, old tasks aren't being deleted: check that `cron_queue_loader.php` is scheduled, because that's what queues it, and both workers can read **Running** while it's missing.
We keep failed tasks three times longer than completed ones by default because failures are the ones you go back to. A completed email task is rarely interesting a month later; the failed one is your evidence for why a control owner never got their reminder.
The values are stored as the `QUEUE_RETENTION_COMPLETED_DAYS` and `QUEUE_RETENTION_FAILED_DAYS` settings, and you can also read and change them through the API with `GET /api/v2/admin/queue/settings` and `POST /api/v2/admin/queue/settings`. The rest of the monitor is available to admin API keys the same way, under `/api/v2/admin/queue`; see the API documentation at `/api/v2/documentation/` for the request shapes.
## Common pitfalls
- **Restarting a batch of email tasks without checking why they failed.** If the mail server is still broken, every restarted task fails again, and if it was fixed halfway through, some recipients may get the same message twice. Fix the cause, send a test email from the **Mail** settings page, then restart.
- **Reading Duration as run time.** It includes time spent waiting in the queue. A task that shows two hours may have run for ten seconds after waiting behind a backlog.
- **Expecting Cancel to interrupt a task that's already working.** Neither Stop nor Cancel kills work in flight. A single-step task whose work has already started can show **Canceled** while it finishes, so don't restart it straight away or you may run it twice.
- **Treating the failure notification as a count.** One notification per task type per hour stands for every failure of that type in that hour. The **Failed in the last 24 hours** figure and the **Failed** pill give you the real numbers.
- **Deleting failures you haven't diagnosed.** A deleted failed task takes its error and its payload with it. Find out why the batch failed first; the **Failed in the last 24 hours** count dropping to zero doesn't mean the cause went away.
- **Setting retention to 0 and forgetting about it.** The table never shrinks, free-text search has more rows to scan every month, and payloads can include email bodies you may not want to hold forever.
## Related
- [Troubleshooting Common Issues](https://support.simplerisk.com/kb/12-04-troubleshooting-common-issues?hsLang=en)
- [Monitoring SimpleRisk](https://support.simplerisk.com/kb/12-01-monitoring-simplerisk?hsLang=en)
- [The Cron Jobs](https://support.simplerisk.com/kb/02-07-the-cron-jobs?hsLang=en)
- [Settings Reference](https://support.simplerisk.com/kb/13-01-config-settings-reference?hsLang=en)
- [The Audit Trail](https://support.simplerisk.com/kb/11-01-the-audit-trail?hsLang=en)
- [Email and the Notification Extra](https://support.simplerisk.com/kb/07-02-email-and-the-notification-extra?hsLang=en)
- [FAQs](https://support.simplerisk.com/kb/faqs?hsLang=en)
- [SimpleRisk Extras](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#main-content)
- [Vulnerability Management Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#vulnerability-management-extra)
- [Team Separation Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#team-separation-extra)
- [Import-Export Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#import-export-extra)
- [Administrator Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#main-content)
- [00 About This Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#00-about-this-guide)
- [01 Installation and Deployment](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#01-installation-and-deployment)
- [02 Upgrades and Maintenance](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#02-upgrades-and-maintenance)
- [03 Users and Permissions](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#03-users-and-permissions)
- [04 Authentication](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#04-authentication)
- [05 Customization](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#05-customization)
- [06 Configuring Risk and Compliance](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#06-configuring-risk-and-compliance)
- [07 Integrations](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#07-integrations)
- [08 The API](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#08-the-api)
- [09 Encryption and Data Security](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#09-encryption-and-data-security)
- [10 Workflows and Automation](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#10-workflows-and-automation)
- [11 Reporting and Auditing](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#11-reporting-and-auditing)
- [12 Operations](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#12-operations)
- [13 Reference](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#13-reference)
- [User Guide](https://support.simplerisk.com/kb/user-guide?hsLang=en#main-content)
- [00 Foundations of GRC](https://support.simplerisk.com/kb/user-guide?hsLang=en#00-foundations-of-grc)
- [01 Risk Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#01-risk-management)
- [02 Compliance Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#02-compliance-management)
- [03 Governance](https://support.simplerisk.com/kb/user-guide?hsLang=en#03-governance)
- [04 Asset and Data Inventory](https://support.simplerisk.com/kb/user-guide?hsLang=en#04-asset-and-data-inventory)
- [05 Threat and Vulnerability Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#05-threat-and-vulnerability-management)
- [06 Assessments](https://support.simplerisk.com/kb/user-guide?hsLang=en#06-assessments)
- [07 Incident Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#07-incident-management)
- [08 Audit and Reporting](https://support.simplerisk.com/kb/user-guide?hsLang=en#08-audit-and-reporting)
- [09 Day-to-Day SimpleRisk](https://support.simplerisk.com/kb/user-guide?hsLang=en#09-day-to-day-simplerisk)
- [10 Continuous Improvement](https://support.simplerisk.com/kb/user-guide?hsLang=en#10-continuous-improvement)
- [SimpleRisk User Guides](https://support.simplerisk.com/kb/simplerisk-user-guides?hsLang=en)
- [Troubleshooting](https://support.simplerisk.com/kb/troubleshooting?hsLang=en)
- [SimpleRisk Hosted](https://support.simplerisk.com/kb/simplerisk-hosted?hsLang=en)
- [How To videos](https://support.simplerisk.com/kb/how-to-videos?hsLang=en)
[](https://www.simplerisk.com)
Copyright © 2026, SimpleRisk, Inc.