Cause and effect alerts
Route: /dash · /dash/external
When one failure produces a burst of secondary alerts (a database goes down and every application that depends on it reports AppUnavailable), ToBeAlert can link those secondary alerts to the one that explains them. The explaining alert is the cause; the alerts linked to it are its effects. Effects are normally suppressed: they stay in the system with their own severity and status, but the dashboard tucks them under their cause so operators see one problem instead of twenty.
See also: Alerts table · Modifiers and tools — Mark as effect · Sending alerts — Cause and effect · Resource graph · Views
| Task | Section |
|---|---|
| Understand the terms | Concepts |
| Know how a link is created | How alerts become effects |
| Link symptoms to the alert on their parent resource | Cause on a parent resource |
| Read grouped rows | On the dashboard |
| Filter or sort by these fields | Columns and TQL |
| Know when effects are released | When a cause stops being an alert |
| Audit the links | History |
Concepts
| Term | Meaning |
|---|---|
| Cause | An alert that has at least one effect pointing to it (Is cause = true, Effects > 0) |
| Effect | An alert whose Cause field holds the ID of another alert (Is effect = true) |
| Suppressed | A flag on the alert. Suppressed rows are dimmed and grouped under their cause on the dashboard. It is independent of the link: an alert can be suppressed without a cause, and an effect can be un-suppressed while it keeps its cause |
Rules that always hold:
- One level only. An alert that has a cause is never a cause itself, and an alert that has effects is never an effect. There are no chains.
- Status does not change. Becoming an effect does not acknowledge, shelve, or close the alert. Severity, timeouts, notifications, and policies keep working on it as on any other alert.
- Suppressed is only a flag. It changes how the dashboard presents the row (dimmed, grouped). It does not hide the alert from views, TQL, history, or the API.
How alerts become effects
| Source of the link | How it works | Where to read more |
|---|---|---|
| The sender | The system that posts the alert includes the ID of the cause (field Cause). The alert is stored as an effect and suppressed unless the sender says otherwise. If the ID does not exist, or points to an alert that is itself an effect, the link is dropped and the alert is created without a cause (the alert history says so). | Sending alerts — Cause and effect |
| A policy | A policy with the Mark as effect modifier decides which alerts are effects (its Conditions) and which alerts can be their cause — either alerts that match Cause conditions, or an open alert on a parent resource of the effect's resource (see Cause on a parent resource) — within a time Window and a Direction. It runs when the alert is received and when you Run the policy by hand. | Modifiers and tools — Mark as effect |
| Un-suppress / suppress by hand | A policy with the classic field modifier suppressed set → false shows an effect again (it keeps its Cause); suppressed set → true dims an alert that has no cause; causeId delete detaches an effect from its cause. | Modifiers and tools — Suppress and un-suppress |
A repeat of an existing alert (same resource, event, and environment) never changes the link or the suppressed flag.
Once an alert has a cause, it is never reassigned to another cause — not by a later policy run, not by a closer cause arriving afterwards. To move an effect under a different cause you must first release it — close or delete its current cause, or run a policy with the field modifiers suppressed set → false and causeId delete (see Suppress and un-suppress with Modify field) — and receive the alert again. Keep policy windows realistic (minutes to a few hours): with a very wide window, any old cause that is still open captures every new effect.
Cause on a parent resource
Instead of describing the cause by its fields, a Mark as effect modifier can take it from the hierarchy of resources: Cause is → Open alert on a parent resource. ToBeAlert keeps a resource graph — which resource is the parent of which, per environment — fed by the alerts themselves (resourceParent / resourceChildren in the payload, see Sending alerts — Resource relations), by the graph API, and by the Resource relation policy modifier.
| Rule | Behavior |
|---|---|
| Which alert is the cause | An open alert — not closed, expired, or deleted, and not already an effect — on a parent, grandparent, or higher ancestor of the effect's resource, up to Max depth levels (1–10, default 5), inside the policy Window. The resourceParent declared by the effect's own alert counts even when the graph has no relation for it yet. Additional cause filters (optional) narrow the candidates, for example to Down events |
| Same environment | Relations and alerts are matched inside the effect's environment. An alert on esx-01 in Production never explains an alert on vm-7 whose environment is empty or spelled differently |
| Nearest first | The alert on the closest ancestor wins (parent before grandparent); at the same distance, the one closest in time |
| Cause arrival | When an alert arrives on a resource that has children in the graph (or open alerts that declare it as parent), the open alerts on its descendants — up to Max depth — that match the policy Conditions and fit the window become its effects. If the policy has Additional cause filters, the arriving alert must match them |
| Flattened, not chained | The one-level rule holds. If the alert on the intermediate resource is already an effect of another alert, it cannot be a cause, so the alert on the child resource is linked directly to that root cause |
| Release | As for any effect: when the cause is closed, expired, cleared, or deleted, the effects are released |
The policy history reason names the parent: Policy "X" marked this alert as an effect (suppressed): alert <id> (<resource> <event>) is an open alert on a parent resource "esx-01". — or … arrived on a parent resource "esx-01". when the cause arrived after the effect. Form fields and a worked example are in Modifiers and tools — Cause on a parent resource.
On the dashboard
- Grouped rows. Whatever column you sort by, suppressed effects are listed right under their cause (the group sorts by the cause's value). An effect that has been un-suppressed sits in its normal sorted position instead. If the page size cuts a group, the remaining effects appear on the next page.
- Expand / collapse column. A fixed, untitled column right after the checkbox:
- In the header, a control that expands or collapses all groups on the page (Expand all effects / Collapse all effects).
- On a cause row, a chevron with a tooltip that counts hidden or shown effects (N hidden effects, click to show).
- On an effect row, a ↳ arrow with the tooltip Effect of <id>. The ID is a link that opens the cause.
- Groups start collapsed; the state is remembered as you work.
- Suppressed rows are dimmed. They return to full opacity when you hover them or select them. Selection, bulk actions, and the context menu work on them like on any row.
The dashboard also ships a built-in view Cause and effect events that lists only causes and effects. Open it from Add view on the tab bar when your administrator has assigned it to you — see Views — Built-in views.
Columns and TQL
Open Column manager on the table toolbar to show these columns (see Alerts table — Table columns):
| Column | TQL field | Content |
|---|---|---|
| Cause | causeId | ID of the cause (empty when the alert is not an effect) |
| Suppressed | suppressed | true / false |
| Effects | effectCount | Number of effects pointing to this alert. Shown by default |
| Is effect | isEffect | true when the alert has a cause |
| Is cause | isCause | true when at least one effect points to it |
All five can be sorted and used in the dashboard search bar and in view queries (TQL or SQL):
| Query | Meaning |
|---|---|
isCause:eq:true | Root problems only |
isEffect:eq:true | Alerts explained by another alert |
suppressed:eq:false | Everything an operator should act on (hides suppressed effects) |
effectCount:gt:0 | Causes, ordered by impact when you sort by Effects |
causeId:eq:<id> | All effects of one cause |
When a cause stops being an alert
An effect is released as soon as its cause stops being an alert:
- the cause is deleted (from the drawer, bulk Delete, the API, or housekeeping), or
- its status becomes closed or expired, or
- its severity returns to normal, ok, or cleared.
Each released effect gets an empty Cause and Suppressed = false, so it reappears as a normal row in its own sorted position. Released effects are not re-attached to another cause automatically; a policy can link them again only if the alert is received again. Deleting or closing an effect never touches its cause.
History
Alert history records every change to the link:
| Entry | When | What you see |
|---|---|---|
| Policy execution | A policy marked the alert as an effect | Actor: the policy. Reason: Policy "X" marked this alert as an effect (suppressed): alert <id> (<resource> <event>) matched the cause conditions. — or, for a cause found on a parent resource, … is an open alert on a parent resource "esx-01". / … arrived on a parent resource "esx-01". Diff: suppressed: false → true, causeId: — → <id> |
| New | The sender posted the alert with a cause | The link is part of the received data — there is no policy entry. If the requested cause was invalid, the entry says the cause was ignored |
| Release | The cause was deleted, closed, expired, or cleared | Actor system. Reason: Cause alert <id> (…) is no longer an alert (status closed): this alert is no longer suppressed. |
Open them from the details drawer or the per-alert timeline.
Example: database outage
db-prod-01DatabaseDown (critical) arrives.- A policy Suppress app alerts behind a DB outage has Conditions
eventEqualsAppUnavailableand a Mark as effect modifier with Cause conditionseventEqualsDatabaseDown, Window 30 Minutes, Direction Before or after. jboss-01AppUnavailable (major) arrives one minute later. The policy finds the open DatabaseDown inside the window and links it:jboss-01is now a dimmed effect underdb-prod-01.- The monitoring system posts
jboss-02AppUnavailable itself with the cause ID ofdb-prod-01: it is linked by the sender, no policy entry. - An operator sorts by Effects:
db-prod-01is at the top with 2, both effects under it. - The database recovers and DatabaseDown is closed. Both effects are released, un-dimmed, and listed on their own — if they are still open, somebody has to look at them.
Payloads for this scenario are in Sending alerts — Cause and effect.
Best practices
- Write cause conditions for root problems (host down, database down, network link) and effect conditions for the symptoms that always follow them. When your alerts or a CMDB already describe the hierarchy, use Cause is → Open alert on a parent resource instead and keep Max depth low — one policy then covers every host and application in the resource graph.
- Keep windows short. Thirty minutes is usually enough; an effect is never moved later, so a wide window silently parks new symptoms under stale causes.
- Sort by Effects during an incident to find the alert that explains the most noise.
- Filter
suppressed:eq:falseon operator views so dimmed rows do not distract, and keep Cause and effect events for reviewers. - Check history when an effect looks wrong: the policy entry tells you which cause matched and why.