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:
bobbanandClaude Sonnet 5.5 committed 2026-10-21 20:25:45 +02:00
1 parent c2e76262ca
commit 0277126add
12 files changed
+887

No files matched your search

+28
View File
@@ -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