What changed before this? on every incident, ranked
- A card on the incident page, and GET /api/incidents/:id/before and /api/v1/incidents/:id/before: what the app knows happened in the 30 min to 24 h before an alert began (audit log, maintenance windows, update runs and patch plans, other alerts, a step in the server's own figures), scored by how related, what kind and how close - A host going down is shown once; Likely, Possible and Background; at most ten - Docs and roles updated Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
c2e76262ca
commit
0277126add
12 files changed
+887
No files matched your search
+28
@@ -57,6 +57,7 @@ curl -H "Authorization: Bearer hlm_p_xxxxxxxxxxxxxxxxxxxxxxxx" https://hm.exampl
|
||||
| `GET /api/v1/alerts` | What is wrong now. Filter with `?severity=`, `?category=`, `?acknowledged=true\|false`, `?silenced=true\|false`. |
|
||||
| `GET /api/v1/incidents` | The record of alerts that began and ended. `?status=open\|resolved`, `?limit=` (1–500, default 100). |
|
||||
| `GET /api/v1/incidents/:id` | One incident with its timeline. |
|
||||
| `GET /api/v1/incidents/:id/before?minutes=` | What changed before it began, ranked by how likely each is to be connected. `minutes` 15–1440 (120 by default). |
|
||||
| `GET /api/v1/inventory` | The hardware inventory. |
|
||||
| `GET /api/v1/network` | Network equipment read from UniFi: devices, networks, Wi-Fi names, and which server is plugged into which device. |
|
||||
| `GET /api/v1/endpoints` | The endpoint checks and how they are doing. |
|
||||
@@ -201,6 +202,33 @@ An *incident* is one time an alert was raised and later went away; the same aler
|
||||
`GET /api/v1/incidents/:id` adds the **timeline** (when it was raised, acknowledged, handed over, what was done to the thing it is about in the hour around it, when it resolved) and the notes
|
||||
people wrote. Open incidents are always listed; resolved ones newest first, up to `limit`.
|
||||
|
||||
### `GET /api/v1/incidents/:id/before`
|
||||
|
||||
The "what changed before this?" list for one incident: what the app knows happened in the window before it began — settings and other changes in the audit log, maintenance windows that began or ended, update runs
|
||||
and patch plans, other alerts raised first, and a step in the server's own figures — each scored and the best first.
|
||||
|
||||
```json
|
||||
{ "incidentId": 1, "openedAt": "2026-10-21T20:08:08.000Z", "windowMinutes": 120,
|
||||
"from": "2026-10-21T18:08:08.000Z", "to": "2026-10-21T20:09:08.000Z",
|
||||
"suspects": [
|
||||
{ "at": "2026-10-21T20:02:08.000Z", "minutesBefore": 6, "kind": "maintenance", "title": "Maintenance on pve1 ended", "detail": "Kernel update", "actor": "Olga",
|
||||
"relation": "needs", "about": "pve1 — which it needs", "why": "About something it needs directly, 6 min before",
|
||||
"score": 86, "confidence": "likely", "link": "/maintenance" }
|
||||
],
|
||||
"looked": { "auditEntries": 5, "maintenanceWindows": 1, "updateRuns": 1, "otherAlerts": 2, "series": 1 } }
|
||||
```
|
||||
|
||||
| Field | Meaning |
|
||||
|---|---|
|
||||
| `kind` | `maintenance`, `update`, `alert` (another alert, or a host going down), `change`, `settings`, `metric` (a step in the server's own load, memory or disk) or `rule` (one of your alert rules was changed). |
|
||||
| `relation` | How it is related to what the incident is about: `same`, `needs` (the host it runs on, the switch it is plugged into, something it depends on), `needed_by`, `everything` (a setting, DNS) or `other`. |
|
||||
| `score`, `confidence` | 0–100, from how related it is, what kind of thing it is and how close in time. `likely` is 55 and over, `possible` 25 and over, otherwise `background`. Anything under 8 is left out. |
|
||||
| `minutesBefore` | How long before the incident began. |
|
||||
| `link` | A page in the app, as a path (not a full address). |
|
||||
| `looked` | How much was looked through, so an empty `suspects` can say what it covered. An empty list means *nothing the app knows about*, not *nothing happened* — a change made on the machine itself is invisible to it. |
|
||||
|
||||
At most ten suspects are returned. It is a list of suspects, not a diagnosis.
|
||||
|
||||
### `GET /api/v1/inventory`
|
||||
|
||||
```json
|
||||
|
||||
@@ -244,6 +244,24 @@ timeline — what was done to the thing in the hour around it (maintenance, a re
|
||||
the page open; the same alert coming back is a **new** incident. Resolved incidents are kept **400 days**. They are on **Operations → Alerts → History**, in the read API (`/api/v1/incidents`) and in the
|
||||
monthly report.
|
||||
|
||||
### What changed before an incident
|
||||
|
||||
Each incident page has a **What changed before this?** card (and `GET /api/v1/incidents/:id/before`): the things the app knows happened in the 30 minutes, 2, 6 or 24 hours before the alert began,
|
||||
ranked. The sources are the audit log (settings, DNS, dependencies, integrations, a server being changed, a neighbour going offline or filling up), maintenance windows that began or ended, update runs and patch
|
||||
plans, other alerts raised first, and a step in the server's own figures (a disk that jumped, memory that fell away).
|
||||
|
||||
Each is scored from three things:
|
||||
|
||||
| | How it counts |
|
||||
|---|---|
|
||||
| **How related** | The **same thing** the incident is about counts most; then **something it needs** (the host it runs on, the switch it is plugged into, a dependency you wrote — the nearest count more); then a **change that touches everything** (a setting, DNS); then **something that needs it**; and last something with **no link** the app knows of. |
|
||||
| **What kind** | A maintenance window ending or a host going down is likelier than a change of settings, which is likelier than a note being written. Logins, notes, runbooks, tags and the like are not listed at all. A setting that bears on this kind of alert (thresholds, routing) counts for more. |
|
||||
| **How close** | A change five minutes before counts for much more than one two hours before — the weight falls off over about an hour and never reaches zero inside the window. |
|
||||
|
||||
They are shown as *Likely* (55 and over), *Possible* (25 and over) and *Background* (the rest, behind a button); under 8 is left out, and at most ten are shown. The audit entry "pve1 stopped reporting"
|
||||
and the alert about it are one event and shown once. It is a **list of suspects, not a diagnosis**: it says what happened and when, not why, and a change made on the machine itself — a package installed by
|
||||
hand, a config file edited — is not something the app can see.
|
||||
|
||||
## History and how long it is kept
|
||||
|
||||
| What | Kept | Grain |
|
||||
|
||||
Reference in new issue
Block a user