feat(api): add memory breakdown metrics (system, vm, docker, zfs cache)

[Richard (rkozyak)]

Exposes per-category memory breakdown metrics for system, vm, docker and zfs cache. Mirroring the Unraid dashboard's ram widget breakdown.

Add four new fields to memory metrics:

• zfsCache
• vm
• docker
• system

Summary by CodeRabbit

• New Features
  • Added GraphQL memory breakdown fields for ZFS cache, virtual machines, and Docker.
  • Added a system memory calculation that reports uncategorized RAM after subtracting known sources.
  • Memory source values gracefully handle unavailable readings by returning null/zero where appropriate.
• Tests
  • Added unit tests for memory breakdown collection, including ZFS/VM/Docker parsing and failure behavior.
  • Added assertions covering both sequential and concurrent caching reuse of collected sources.

CLD-709

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[coderabbitai]

Walkthrough

Adds a cached memory breakdown service for ZFS, VM, and Docker usage, exposes those values plus computed system memory through GraphQL, and registers the new resolver and service in the metrics module.

Changes

Memory Breakdown Feature

Layer / File(s)	Summary
MemoryBreakdownService implementation and caching api/src/unraid-api/graph/resolvers/info/memory/memory-breakdown.service.ts, api/src/unraid-api/graph/resolvers/info/memory/memory-breakdown.service.spec.ts	Defines nullable ZFS/VM/Docker source values, caches collected results briefly, reads and aggregates memory from arcstats, virsh, and Docker cgroups, and tests parsing plus sequential and concurrent cache reuse.
GraphQL resolver and module wiring api/src/unraid-api/graph/resolvers/info/memory/memory.model.ts, api/src/unraid-api/graph/resolvers/info/memory/memory-utilization.resolver.ts, api/src/unraid-api/graph/resolvers/info/memory/memory-utilization.resolver.spec.ts, api/src/unraid-api/graph/resolvers/metrics/metrics.module.ts	Adds nullable GraphQL fields for categorized and system memory, resolves them from the breakdown service, verifies passthrough and system calculations, and registers the resolver and service in MetricsModule.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
participant GraphQLClient
participant MemoryUtilizationResolver
participant MemoryBreakdownService
participant MetricsModule
MetricsModule->>MemoryBreakdownService: provide service
MetricsModule->>MemoryUtilizationResolver: provide resolver
GraphQLClient->>MemoryUtilizationResolver: query zfsCache/vm/docker/system
MemoryUtilizationResolver->>MemoryBreakdownService: getSources()
MemoryBreakdownService-->>MemoryUtilizationResolver: MemoryBreakdownSources
MemoryUtilizationResolver-->>GraphQLClient: resolved memory fields

Loading

Poem

A rabbit hops through bytes at night,
Counting cache and VM just right.
Docker whispers, ARC replies,
System memory sums the pies.
🐇✨ Hop, hop — the graphs take flight.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: adding API memory breakdown metrics for system, VM, Docker, and ZFS cache.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Exposes additional per-category memory usage fields on the existing MemoryUtilization GraphQL type to mirror the Unraid dashboard RAM breakdown, backed by a new service that collects ZFS ARC, VM, and Docker memory usage with short-lived caching.

Changes:

• Adds MemoryBreakdownService to collect ZFS ARC cache size, active VM balloon RSS, and Docker container cgroup memory usage (with caching).
• Adds MemoryUtilizationResolver to expose zfsCache, vm, docker, and computed system fields on MemoryUtilization.
• Adds unit tests for the new resolver and service behaviors (including caching).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
api/src/unraid-api/graph/resolvers/metrics/metrics.module.ts	Registers the new memory breakdown service + resolver in the metrics GraphQL module.
api/src/unraid-api/graph/resolvers/info/memory/memory-utilization.resolver.ts	Adds GraphQL field resolvers for zfsCache, vm, docker, and system.
api/src/unraid-api/graph/resolvers/info/memory/memory-utilization.resolver.spec.ts	Unit tests for per-field passthrough and system calculation/clamping behavior.
api/src/unraid-api/graph/resolvers/info/memory/memory-breakdown.service.ts	Implements collection logic for ZFS/VM/Docker memory sources with a TTL cache.
api/src/unraid-api/graph/resolvers/info/memory/memory-breakdown.service.spec.ts	Unit tests for each source collector and cache behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 93.95973% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 52.85%. Comparing base (2679fda) to head (a324f67).

Files with missing lines	Patch %	Lines
.../resolvers/info/memory/memory-breakdown.service.ts	95.23%	5 Missing ⚠️
...id-api/graph/resolvers/info/memory/memory.model.ts	50.00%	4 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #2036 +/- ##
==========================================
+ Coverage 52.77% 52.85% +0.08% 
==========================================
Files 1035 1037 +2 Lines 72060 72208 +148 Branches 8303 8337 +34 ==========================================
+ Hits 38031 38168 +137 - Misses 33903 33914 +11 
Partials 126 126 

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[SimonFair]

I have view the metrics to confirm they are pulling the same values as the UI dashboard. Tests for both query and subscription comleted

[SimonFair]

Eli Bosley (@elibosley) This is fine to merge in my view.