Skip to content

Enhance Healthchecks with up/down livestats - #1027

Merged
KodeStar merged 2 commits into
linuxserver:masterfrom
steven-s-martins:enhance-healthchecks
Sep 11, 2026
Merged

Enhance Healthchecks with up/down livestats#1027
KodeStar merged 2 commits into
linuxserver:masterfrom
steven-s-martins:enhance-healthchecks

Conversation

@steven-s-martins

Copy link
Copy Markdown
Contributor

Summary

Add enhanced support to the existing Healthchecks app so the tile shows Up / Down check counts, similar to Uptime Kuma and Kuvasz Uptime. Implementation follows the Kuvasz Uptime pattern closely (JSON list endpoint, API-key header, Up/Down livestats, dataonly refresh).

  • Stats (tile): Up / Down (counts by check status)
  • Endpoint: GET /api/v3/checks/ for both Test and livestats
  • Auth: API key via X-Api-Key header (read-only keys work)
  • Cadence: dataonly=1 — up/down counts refresh on the 30s interval
  • Statuses counted: up and down only (new / grace / paused are ignored)

Test plan

Tested against my self-hosted Healthchecks and Heimdall instances:

  • Config Test succeeds with a valid API key and fails with a bad/missing key
  • Tile Up/Down counts match GET /api/v3/checks/
  • Read-only API key works for listing checks

Show check up/down counts on the tile via the Management API, matching other uptime-style enhanced apps.
The Management API returns 401 with a { "error": ... } body when the
API key is missing or revoked, and execute() is configured with
http_errors => false, so that body reaches livestats() as a stdClass
with no "checks" property. Reading it directly raised an undefined
property warning, which Laravel promotes to an ErrorException, so
get_stats returned a 500 and the tile broke instead of falling back to
zeroed counts.

Coalesce the property to null so a malformed or error response leaves
the tile inactive, and flip the status to active only when a real
checks array came back - matching the KuvaszUptime pattern this app
follows.
@KodeStar

Copy link
Copy Markdown
Member

Reviewed and merging — thanks for this, the Kuvasz pattern was the right one to follow here.

I pushed one fix onto the branch before merge. execute() is configured with http_errors => false, so a 401 from a missing/revoked API key comes back as a real response whose body is {"error": "wrong api key"} — a stdClass with no checks property. is_object($body) ? $body->checks : [] read that property directly, which raises an undefined-property warning; Laravel promotes that to an ErrorException, so get_stats returned a 500 and the tile errored out instead of falling back to zeroed counts.

The fix coalesces to null ($body->checks ?? null) so a malformed or error response leaves the tile alone, and moves the active status onto the success path — KuvaszUptime flips to active when the list parses, and the original always returned inactive. With dataonly=1 that only affects the refresh cadence, but it keeps the two apps consistent.

@KodeStar
KodeStar merged commit dbac879 into linuxserver:master Sep 11, 2026
3 checks passed
@LinuxServer-CI LinuxServer-CI moved this from PRs to Done in Issue & PR Tracker Sep 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Development

Successfully merging this pull request may close these issues.

3 participants