Check a value, not just "is it up": JSON value checks on web endpoints

A web check can read a value out of a JSON answer (power.now, state,
data.result[0].value[1]) and judge it: below, above, equal to, contains, is there.
The value read is shown on the Endpoints page, charted under History, exported as
homelab_endpoint_value and in the read API. A check can also send one header (a
token), stored encrypted, never returned, and not forwarded to another host on a
redirect.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-21 21:13:44 +02:00
1 parent e114567d64
commit 3cb3e4988f
21 files changed
+6804 -47

No files matched your search

+3 -3
View File
@@ -253,15 +253,15 @@ device (and port). Wi-Fi passphrases are never read, so they are never here.
{ "endpoints": [
{ "id": 1, "name": "Wiki", "kind": "http", "target": "https://192.168.1.20/", "port": null, "enabled": true,
"status": "up", "lastCheckedAt": "2026-10-20T21:50:00.000Z", "lastResponseMs": 41, "lastMessage": null,
"certificateExpiresAt": "2027-01-04T12:00:00.000Z", "uptime24hPercent": 100, "uptime7dPercent": 99.9,
"value": null, "certificateExpiresAt": "2027-01-04T12:00:00.000Z", "uptime24hPercent": 100, "uptime7dPercent": 99.9,
"averageResponseMs24h": 44, "serverId": 1 }
] }
```
`status` is `up`, `down`, `unknown` (never asked yet) or `paused` (switched off). `lastMessage` is set only while it is failing (why). `kind` is `http`, `tcp` or `tls`.
`status` is `up`, `down`, `unknown` (never asked yet) or `paused` (switched off). `lastMessage` is set only while it is failing (why). `kind` is `http`, `tcp` or `tls`. `value` is null unless the check judges a value in the answer, and then `{ "path": "power.now", "operator": "<", "expected": "5000", "unit": "W", "last": "120" }` (`last` is what it read the last time, as text).
`/:id/history?days=` answers `{ check: {id, name}, … points … }`: the availability and answer times over 1–365 days, drawn from each answer (up to 2 days), the hourly figures (up to 120 days) or the daily
ones, whichever is fine enough and still kept.
ones, whichever is fine enough and still kept. A check that judges a value also has `values` — `{ unit, days, points: [{t, v, lo, hi}], latest, lowest, highest }` — over as much of that stretch as results are kept (14 days); otherwise `values` is null.
### `GET /api/v1/maintenance`
+10 -1
View File
@@ -150,7 +150,7 @@ offline or has not reported for 45 minutes is not judged.
| Kind | What it asks |
|---|---|
| `http` | Fetches an `http(s)://` address. Counts as up if the status is in the accepted set (200–399 unless you say otherwise, e.g. `200-299, 301`), and — if you ask — the page contains a keyword. Follows up to 5 redirects. |
| `http` | Fetches an `http(s)://` address. Counts as up if the status is in the accepted set (200–399 unless you say otherwise, e.g. `200-299, 301`), and — if you ask — the page contains a keyword, and/or **a value in a JSON answer is within its limit** (see below). Follows up to 5 redirects when it has a keyword or value to look for. |
| `tcp` | Opens a connection to a host and port. |
| `tls` | Connects and reads the certificate; the answer is the days left. |
@@ -159,6 +159,15 @@ optional **server it is linked to** (maintenance on that server silences it, and
daily summaries for the charts and uptime figures.
- A check **fails an alert** (critical) after the configured number of failures in a row, and is announced as resolved when it works again. A **certificate** within its warning days is its own alert (`endpoint-cert:…`).
- **Checking a value, not just "is it up".** A web check can read a number or a word out of a JSON answer and judge it. Say **where** it is — `power.now`, `state`, `items[2].name`, or for a Prometheus query
`data.result[0].value[1]` (`[0]` is the first place in a list; `["a.b"]` for a name with a dot in it) — and **how it should compare**: *is below*, *is at most*, *is above*, *is at least*, *is equal to*, *is anything but*,
*contains*, or *is there*. A number given as text (`"42.5"`, which is how Prometheus gives them) counts as a number; equality compares numbers as numbers and anything else as the same text, capital letters
included. An optional **unit** (`W`, `%`) is shown after a number. The status is judged first, then the value: a value outside its limit is a failure that says so ("power.now is 5200 W, but should be below 5000 W"),
and the alert reads *Meter — power.now is 5200 W, but …* rather than "isn't answering". It is also a failure if the answer isn't JSON, the path isn't in it ("it stops at power"), or the answer is more than 64 KB.
The value read is remembered with each result: shown in the *Answer* column, charted under **History…** (as far back as results are kept, 14 days), in `/metrics` as `homelab_endpoint_value` (numbers only) and in the read API.
Examples: Home Assistant's `/api/states/sensor.power` (path `state`), a Plex or Frigate status, an inverter's output, a Prometheus query (`/api/v1/query?query=…`).
- **A header, for an API that wants a token.** A web check can send one header with its request (usually `Authorization: Bearer …`). The value is stored **encrypted** when `CREDENTIALS_ENCRYPTION_KEY` is set, is never sent back
to the browser (the form says *Saved — leave blank to keep it*), and goes only to the address you gave — **not to another host a redirect leads to**.
- What an administrator types in cannot be just anything: loopback, link-local and cloud-metadata addresses are refused, and the connection goes to the one address that passed the check. LAN and public hosts are fine.
- The app suggests checks it can already work out (a web port a server's agent sees open, a secret with a host) under *Endpoints → Suggested*, and proxied hosts Nginx Proxy Manager serves.
+1
View File
@@ -290,6 +290,7 @@ All gauges. The same table is checked by a test against what `/metrics` really s
| `homelab_backup_last_age_seconds` | `guest`, `vmid`, `integration` | How long ago a guest's newest backup was. |
| `homelab_endpoint_up` | `name`, `kind` | 1 if the endpoint check's last answer was fine, else 0; left out until it has been asked. |
| `homelab_endpoint_response_milliseconds` | `name`, `kind` | How long it took to answer the last time. |
| `homelab_endpoint_value` | `name`, `kind` | The number a value check last read from the answer (checks that judge a value only, and only when it is a number). |
| `homelab_endpoint_certificate_days_left` | `name`, `kind` | Days until the certificate it shows expires (negative once it has). |
| `homelab_heartbeat_up` | `name` | 1 if the job has reported in time and not said it failed, else 0; switched-off heartbeats are left out. |
| `homelab_heartbeat_last_ping_timestamp_seconds` | `name` | When the job last reported that it finished (Unix time). |