Skip to content

Feature: read System Summary figures from the Unraid API - #125

Merged
SandObserver merged 2 commits into
mainfrom
feat/system-summary-unraid
Aug 18, 2026
Merged

SandObserver merged 2 commits into
mainfrom
feat/system-summary-unraid

Conversation

@SandObserver

@SandObserver SandObserver commented Aug 18, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • Add unraid to statProvider, with unraidUrl and an unraidApiKey secret.
  • Declare a fourth copy of the slots group: no IO Wait and no Processes, since neither exists in the schema, share-name labels for the two disk fields, and a group hint naming what the source does not report.
  • POST one query to /graphql with an x-api-key header, building it from the slots in use so shares and array are only requested when a slot needs them.
  • Map metrics.cpu.percentTotal and metrics.memory.percentTotal, metrics.temperature.sensors by name, a user share or the array capacity for a disk slot, and info.os.uptime as a boot time converted to elapsed seconds.
  • Convert sensor readings to Celsius, covering the Fahrenheit, Kelvin and Rankine units the schema declares.
  • Report a GraphQL errors entry as written, classifying it by its own extensions.code, since neither a refused key nor an insufficient role produces a 401.
  • Measure a share against its own size limit, or against what is used plus what is left on the pool when no limit is set, which is the usual case.
  • Name disabled temperature reporting rather than presenting an empty sensor picker.

Reading a machine from the dashboard running beside it is most useful where Stackyard is installed on the machine itself, which is how the Unraid Community Applications install runs it.

Testing
All green, including the Docker build. Added 12 tests for the provider, covering the request shape, slot mapping, unit conversion, share versus array, a share with no size limit, boot-time arithmetic, conditional query building, and each failure kind.

Verified end to end against Unraid's own API server, run from the unraid/api development image with its state fixtures, using a key issued by its own CLI. That run corrected two things a schema reading had wrong: a share reports size as its limit, which is 0 unless one is set, and a refused key returns 200 with a GraphQL error rather than 401. Confirmed live: CPU and memory, uptime from boot time, a named share, the array total, an unknown share reading empty, temperature resolving to null with reporting disabled, a refused key, and a key whose role does not reach the resource.

Checklist

  • Stays within the project constraints: one container, no runtime dependencies, no build step (see CONTRIBUTING.md).
  • Tests added or updated for new logic, and the full suite, lint, and typechecks pass.
  • Docs updated if behavior or configuration changed.
  • CHANGELOG.md updated under Unreleased if the change is user-visible.

Adds Unraid as a source alongside Beszel, Glances and the local machine. One
GraphQL query returns CPU and memory utilisation, temperatures by sensor name,
and the boot time that becomes the uptime. A disk slot names a user share, or is
left empty for the array as a whole. Neither IO wait nor a process count exists
anywhere in the schema, so the slot does not offer them.

Shares and the array sit behind their own permissions, so they are only asked
for when a slot needs them, and a key limited to metrics still works. Sensor
readings are converted to Celsius, since the API reports whichever unit the
server is set to. Temperature reporting ships disabled and resolves to null
rather than failing, so the picker names that instead of showing no sensors.
@SandObserver SandObserver added the enhancement New feature or request label Aug 18, 2026
…s them

A share's size field is its own limit and is 0 unless one is set, so a share
was measured against nothing and always read as empty. What is used plus what
is left on the pool is the only total available, and is now the fallback.

An API key the server refuses does not produce a 401. The request succeeds and
the rejection arrives as a GraphQL error, so the status code alone never
reports it. The error's own code now decides, covering both a refused key and a
key whose role does not reach the resource.
@SandObserver
SandObserver merged commit b2e47b9 into main Aug 18, 2026
4 checks passed
@SandObserver
SandObserver deleted the feat/system-summary-unraid branch August 18, 2026 21:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant