Skip to main content
PathMon

Chapter 17 of 26

Alerts Overview

Updated Read the full guide

What alerts are in PatchMon

An alert is a record of a noteworthy condition detected by the server: a host that has stopped reporting, a security-updates threshold being crossed, a new PatchMon server version becoming available, and so on. Alerts appear in Reporting and can be routed to chat, email, or ntfy through the notifications pipeline. The same event that creates an alert can also be sent to external destinations. Alerts are the in-app representation of operational signals.

Alerts are grouped into categories in Settings and the UI: host, patching, compliance, docker, security, remote_access, and system.

The global master switch lives under Reporting → Alert Lifecycle → Alerts system. When this is off, no alerts are created at all, regardless of per-type configuration.

Alert types implemented today

The following alert types fire from the server code in 2.0. Each can be individually enabled, tuned, and routed.

Type Category Fired when
host_down host The host's agent WebSocket has been disconnected for longer than the host_down threshold (default 30 seconds, configurable in Reporting → Alert Lifecycle), or the host has not reported within that threshold during a periodic check. Displayed as Host Agent Down.
host_recovered host A previously-down host's agent reconnects or its agent starts reporting again. Displayed as Host Agent Recovered.
host_enrolled host A new host is successfully enrolled
host_deleted host A host is removed from the inventory
host_security_updates_exceeded security A host has more security updates than the configured threshold
host_pending_updates_exceeded security A host has more pending updates than the configured threshold
host_security_updates_resolved security Security updates count drops below threshold again
host_pending_updates_resolved security Pending updates count drops below threshold again
server_update system A newer PatchMon server version is detected via the DNS version check
agent_update system A newer agent version is released
patch_run_started patching A patch run begins
patch_run_completed patching A patch run finishes
patch_run_failed patching A patch run exits with errors
patch_run_approved patching A patch run is approved for execution
patch_run_cancelled patching A patch run is cancelled by an operator
patch_reboot_required patching Packages requiring a reboot were installed
compliance_scan_completed compliance An OpenSCAP compliance scan finishes
compliance_scan_failed compliance A compliance scan errors out
container_stopped docker A tracked Docker container stops unexpectedly
container_started docker A previously-stopped container starts again
container_image_update_available docker A newer image digest is available for a tracked container
ssh_session_started remote_access A user opens a web SSH session to a host
rdp_session_started remote_access A user opens a web RDP session to a host
user_login system A user signs in
user_login_failed system A failed sign-in attempt
account_locked system An account is locked after repeated failures
user_created system A new user is created
user_role_changed system A user's role is changed
user_tfa_disabled system A user's two-factor authentication is removed

If a type listed in the release notes is not in this table, it is not implemented in the server. Anything absent from the alert_config table is treated as enabled by default for backwards compatibility, but only types with emitters in the server code actually fire.

The Reporting page

Alerts are managed from Reporting in the main navigation. The page has a fixed header with four severity cards (Informational, Warning, Error, Critical) plus a Total Active card, and a tab bar underneath.

Tabs

Tab Purpose
Overview Dashboards: alerts by severity, volume trend, alerts by type, recent alerts, responder workload, deliveries by destination
Alerts The filterable table of open and historical alerts
Alert Lifecycle Per-type configuration (gated by the alerts_advanced module)
Destinations Notification destinations (SMTP, webhook, ntfy, internal)
Event Rules Routing rules that fan events out to destinations
Scheduled Reports Cron-scheduled fleet reports delivered to destinations
Delivery Log Every outbound notification attempt, with status and errors

Clicking any severity card jumps straight to the Alerts tab filtered to that severity and status = open.

Filters

The Alerts tab supports four filters in addition to a free-text search box:

Filter Values
Severity All Severities, Informational, Warning, Error, Critical
Type All Types or any alert type that exists in your alert history
Status All Status, Open, Acknowledged, Investigating, Escalated, Silenced, Done, Resolved
Assignment All Assignments, Assigned to me, Assigned, Unassigned, or a specific responder

Filters persist in the URL (?tab=alerts&severity=critical&status=open), so you can deep-link directly to a filtered view. The severity cards in the header also highlight when a filter is active.

Filtering and searching are applied by the server across every alert, not just the alerts on the page you are looking at, so a search always returns matches from the whole history. The search box waits briefly after you stop typing before it runs, so results settle rather than flickering on every keystroke.

Sorting

Three columns in the alerts table are sortable by clicking the header: Severity, Type, and Created. The arrow icon next to the column header indicates the current sort direction. Sorting is applied across the whole filtered set, so the first page always shows the true top of the sort.

Pagination

The alerts table is paginated. Below the table you will find:

  • Rows per page: 25, 50, 100, or 200. Your choice is remembered in the browser.
  • A count of the rows shown and the total number of alerts matching the current filters.
  • Previous and next page controls, with the current page number.

Changing a filter, the search text, the sort, or the page size returns you to page one. Any row selection is cleared when you change page or filter, so a bulk action can only ever apply to alerts you can see.

Alert lifecycle

PatchMon tracks alerts with two concepts:

  • is_active: a boolean on the alert row. An alert is active when it is open or still being worked on, and inactive once it has been resolved.
  • Current state: a label derived from the most recent action recorded against the alert (e.g. acknowledged, resolved).

Actions

The available actions are driven by a database table rather than being hardcoded, so the list may vary slightly between deployments. Actions split into two groups:

Workflow actions keep the alert active and just record progress. Typical names:

  • acknowledged
  • investigating
  • escalated
  • silenced

Resolution actions close the alert: they set is_active=false, record resolved_at and resolved_by, and move the alert out of the active stats. Typical names:

  • resolved
  • done

Running a resolution action on an already-resolved alert is safe. Running a workflow action on a resolved alert re-activates it (this is how "reopen" works in practice: pick a workflow action like acknowledged).

Workflow actions appear under Workflow and resolution actions under Resolve in both the row menu and the alert details modal.

Assignment

Alerts can be assigned to a user from three places:

  1. The Assigned To dropdown on the alerts table: changes the assignment inline.
  2. The Assigned To dropdown in the alert details modal.
  3. The Auto-assign column in Alert Lifecycle: sets a default assignee for all new alerts of a given type.

Choose Unassigned to clear. Every assignment change is written to the alert history.

History

Every action (created, assigned, unassigned, acknowledged, resolved, and any custom action) is recorded in alert_history. Open the alert details modal and scroll to History to see who did what and when. System-driven actions (e.g. host_recovered auto-resolving a host_down alert) are recorded with user "System".

Bulk actions

Select one or more alerts using the checkboxes in the Alerts tab to reveal a bulk-actions bar above the table. You can:

  • Apply any workflow or resolution action to every selected alert in one call.
  • Delete the selected alerts permanently.

Bulk updates stream through the same history recording as individual actions. Deleting an alert does not leave a history trail; use a resolution action if you want to keep the audit record.

The number of selected alerts is shown on the left. Use the checkbox in the table header to select or deselect every row on the current page. Selection does not carry across pages: to act on more alerts at once, raise the rows-per-page setting first.

Per-alert-type configuration

Each alert type has its own row in Reporting → Alert Lifecycle. This tab is gated by the alerts_advanced module; plans without it show an upgrade prompt here.

Each row exposes:

Column Meaning
Active Master switch for this alert type. When off, no alerts of this type are created and no notifications are emitted.
Severity Default severity applied to new alerts of this type.
Alert delay Seconds to wait before delivering the outbound notification. If a cancelling counterpart event (e.g. host_recovered for host_down) fires within the delay window, the notification is suppressed. Useful for flappy hosts.
Frequency For periodic checks only (host_down, host_security_updates_exceeded, host_pending_updates_exceeded). Minutes between checks.
Threshold For threshold alerts. Numeric threshold above which an alert fires. Units depend on the alert type: host_security_updates_exceeded and host_pending_updates_exceeded use a count (number of pending updates); host_down uses seconds (how long the agent's WebSocket can be disconnected before the alert fires). The host_down row shows a sec suffix to make this explicit; default is 30 seconds.
Auto-assign Toggle plus user picker: any new alert of this type is assigned to the chosen user automatically.
Retention Days to keep alerts of this type before cleanup. Empty = never auto-clean.
Auto-resolve Days after which active alerts auto-resolve if no one touches them.

Changes are staged locally. Use the Apply button on the top bar to save them, or Discard to revert. The browser warns you if you navigate away with unsaved changes.

Cleanup

Below the table, the Alert cleanup card runs the retention policy:

  • Preview cleanup shows the list of alerts that would be deleted under the current retention and auto-resolve rules.
  • Delete N alerts commits the preview. The action is irreversible.

Cleanup only deletes alerts that satisfy retention_days. Whether it also deletes unresolved alerts is governed by cleanup_resolved_only per type (default: resolved only).

Permissions

Permission What it grants
can_manage_alerts Create/modify alert configurations, run cleanup, act on alerts
can_manage_notifications Create, edit, test, and delete destinations, routes, and scheduled reports
can_view_notification_logs Read the Delivery Log tab
can_view_hosts List host groups and hosts when building routes and reports

Admins and superadmins bypass these checks. Regular users without can_manage_alerts can still view the Alerts tab but cannot perform actions.