[Feature]: Summarized Memory Used/Usage and Summarized Docker CPU usage

[ABEIDO]

📂 Feature Category

System Monitoring - CPU, RAM, temperatures, uptime

🎯 Use Case / Problem Solved

Im have a few readings left until i can remove glances to monitor my unraid an go all in on HA-Unraid.

It would be nice if HA-Unraid could have a couple of summarized sensors regarding memory and cpu, i guess one can do it with helpers but i always prefer to keep it as simple as possible.

Unraid already shows this memory data under the system card on dashboard view. And total docker cpu usage under docker tab.

💡 Proposed Solution

Add following as summarized sensors:
Docker total CPU usage (%)
System used memory (mb)
System memory usage (%)
ZFS Cache used memory (mb)
ZFS Cache memory usage (%)
Docker used memory (mb)
Docker memory usage (%)

🔄 Alternatives Considered

Workaround:
Group Helpers

🖥️ Unraid Context

Unraid 7.2.4

📊 Priority Level

Medium - Would improve my experience

🤝 Contribution

• I'm willing to test development versions
• I can help with documentation
• I have programming skills and could contribute code
• I can provide detailed requirements and feedback

📝 Additional Context

✅ Checklist

• I have searched existing open and closed issues to ensure this isn't a duplicate
• I have clearly described the problem this feature would solve
• I understand that feature requests might take time or not be implemented if they are not within project scope

[coderabbitai]

Coding Plan

Summary

• Implement Docker aggregate memory sensors by parsing and summing container WebSocket stats, providing both absolute bytes and percentage of system RAM
• Follow existing sensor patterns with class-level attributes, WebSocket manager injection, and disabled-by-default configuration
• Document that ZFS ARC memory sensors cannot be implemented due to API limitations, and that existing RAM sensors already fulfil the "System memory" requirement

Design Choices

Design Choice 1: ZFS ARC memory sensors cannot be implemented

Options Considered:

1. Implement ZFS ARC sensors using available data
2. Document limitation and omit ZFS ARC sensors
3. Request API enhancement from unraid-api upstream

Chosen Option: 2

Rationale: Document the limitation and omit ZFS ARC sensors. The required data simply does not exist in the API, and implementing filesystem-based sensors would be misleading as they don't represent memory usage.

Design Choice 2: System memory sensors already exist with different naming

Options Considered:

1. Create duplicate sensors with "System memory" naming
2. Use existing sensors and document they fulfil this requirement
3. Rename existing sensors (breaking change)

Chosen Option: 2

Rationale: The existing RAM sensors already provide this data. Creating duplicates would add confusion. Users can rename entities in Home Assistant if desired.

Design Choice 3: Docker memory aggregation approach

Options Considered:

1. Parse memUsage strings to extract bytes and compute percentages
2. Sum memPercent values directly (would not represent % of system RAM)
3. Skip Docker aggregate due to complexity

Chosen Option: 1

Rationale: Parse the memUsage strings to extract actual byte values. This allows both accurate total Docker memory (bytes) and meaningful percentage of system RAM calculation. The string format is consistent from the Docker API.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Add Docker Aggregate Memory Sensors

This phase implements two new sensors that aggregate memory usage across all running Docker containers using WebSocket stats data. The sensors follow the existing per-container sensor pattern but iterate all container stats to compute totals.

Task 1: Add Memory String Parsing Utility

Add a helper function to parse Docker memory strings into numeric bytes, enabling aggregation of container memory usage.

• Create parse_docker_memory_string() function in custom_components/unraid/sensor.py near the top of the file with other utility functions
• Function should parse strings like "512MiB / 16GiB" and return the first value (used memory) as integer bytes
• Handle common suffixes: KiB, MiB, GiB, KB, MB, GB with appropriate multipliers
• Return None for unparseable strings to allow graceful degradation

Task 2: Create Docker Total Memory Sensor

Implement a sensor that reports the total memory used by all Docker containers in bytes.

• Create DockerTotalMemorySensor class in custom_components/unraid/sensor.py following the pattern of existing container sensors
• Inherit from UnraidSensorEntity with _attr_translation_key = "docker_total_memory"
• Use SensorDeviceClass.DATA_SIZE with native unit bytes and suggested unit GiB
• Accept ws_manager in constructor, same pattern as ContainerMemoryUsageSensor
• In native_value property: iterate ws_manager.container_stats.stats.values(), parse each memUsage string, and sum the bytes
• Disable by default (_attr_entity_registry_enabled_default = False) to match existing container sensor pattern

Task 3: Create Docker Total Memory Usage Percentage Sensor

Implement a sensor that reports Docker memory as a percentage of total system RAM.

• Create DockerTotalMemoryUsageSensor class in custom_components/unraid/sensor.py
• Inherit from UnraidSensorEntity with _attr_translation_key = "docker_total_memory_usage"
• Use percentage unit with SensorStateClass.MEASUREMENT
• Requires both ws_manager for container stats and coordinator for system memory total
• In native_value: compute total Docker bytes (reusing parsing logic), divide by data.metrics.memory_total, multiply by 100
• Return None if no container stats or system data unavailable
• Disable by default to match existing pattern

Task 4: Add Translation Keys and Icons

Add the required translation strings and icons for the new sensors.

• Add to custom_components/unraid/strings.json under entity.sensor:
  • docker_total_memory: { "name": "Docker total memory" }
  • docker_total_memory_usage: { "name": "Docker total memory usage" }
• Add to custom_components/unraid/icons.json under entity.sensor:
  • docker_total_memory: { "default": "mdi:docker" }
  • docker_total_memory_usage: { "default": "mdi:docker" }

Task 5: Register Sensors in Setup

Wire the new sensors into the entity setup process.

• Modify async_setup_entry in custom_components/unraid/sensor.py
• Add DockerTotalMemorySensor and DockerTotalMemoryUsageSensor instantiation after the per-container sensor loop (around line 2660)
• Only create if system_coordinator.data and Docker is enabled (containers list exists)
• Pass system_coordinator, server_uuid, server_name, and ws_manager to constructors

🤖 Prompt for AI agents

This phase implements two new Docker aggregate memory sensors in
`custom_components/unraid/sensor.py`, along with the supporting utility
function, translation strings, icons, and setup wiring.

**Task 1: Add `parse_docker_memory_string()` utility function**
- Add `parse_docker_memory_string()` near the top of `sensor.py` alongside other
utility functions
- Parse strings in the format "512MiB / 16GiB", extracting only the first value
(used memory) and returning it as integer bytes
- Support suffixes: KiB, MiB, GiB, KB, MB, GB with their correct byte
multipliers
- Return `None` for any unparseable input to allow graceful degradation

**Task 2: Add `DockerTotalMemorySensor` class**
- Inherit from `UnraidSensorEntity`
- Set `_attr_translation_key = "docker_total_memory"`
- Use `SensorDeviceClass.DATA_SIZE`, native unit bytes, suggested display unit
GiB
- Set `_attr_entity_registry_enabled_default = False`
- Accept `ws_manager` in the constructor, following the same pattern as
`ContainerMemoryUsageSensor`
- In `native_value`: iterate `ws_manager.container_stats.stats.values()`, call
`parse_docker_memory_string()` on each `memUsage`, sum valid results and return
total bytes

**Task 3: Add `DockerTotalMemoryUsageSensor` class**
- Inherit from `UnraidSensorEntity`
- Set `_attr_translation_key = "docker_total_memory_usage"`
- Use percentage unit with `SensorStateClass.MEASUREMENT`
- Set `_attr_entity_registry_enabled_default = False`
- Accept both `ws_manager` and `coordinator` in the constructor
- In `native_value`: compute total Docker bytes using
`parse_docker_memory_string()`, divide by `data.metrics.memory_total`, multiply
by 100; return `None` if no container stats or system data is unavailable

**Task 4: Update `strings.json` and `icons.json`**
- In `custom_components/unraid/strings.json` under `entity.sensor`, add:
  - `docker_total_memory`: `{ "name": "Docker total memory" }`
  - `docker_total_memory_usage`: `{ "name": "Docker total memory usage" }`
- In `custom_components/unraid/icons.json` under `entity.sensor`, add:
  - `docker_total_memory`: `{ "default": "mdi:docker" }`
  - `docker_total_memory_usage`: `{ "default": "mdi:docker" }`

**Task 5: Register sensors in `async_setup_entry`**
- In `custom_components/unraid/sensor.py`, locate `async_setup_entry` and after
the per-container sensor loop (around line 2660), instantiate
`DockerTotalMemorySensor` and `DockerTotalMemoryUsageSensor`
- Only instantiate if `system_coordinator.data` is available and Docker is
enabled (containers list exists)
- Pass `system_coordinator`, `server_uuid`, `server_name`, and `ws_manager` to
the constructors

Research

The integration uses a flat structure in custom_components/unraid/ with sensor implementations in sensor.py, coordinators in coordinator.py, and WebSocket handling in websocket.py. Memory sensors follow a concrete class pattern extending UnraidSensorEntity, with class-level attributes for translation keys, units, and state classes. Docker container stats are delivered via WebSocket and stored in UnraidWebSocketManager.container_stats.stats as a dict of DockerContainerStats objects, which include memUsage (string like "512MiB / 16GiB") and memPercent (float). System memory sensors (RAMUsageSensor, RAMUsedSensor) already exist and report combined "System + Docker" memory from SystemMetrics.

---

🚀 Next Steps

🤖 All AI agent prompts combined

This phase implements two new Docker aggregate memory sensors in
`custom_components/unraid/sensor.py`, along with the supporting utility
function, translation strings, icons, and setup wiring.

**Task 1: Add `parse_docker_memory_string()` utility function**
- Add `parse_docker_memory_string()` near the top of `sensor.py` alongside other
utility functions
- Parse strings in the format "512MiB / 16GiB", extracting only the first value
(used memory) and returning it as integer bytes
- Support suffixes: KiB, MiB, GiB, KB, MB, GB with their correct byte
multipliers
- Return `None` for any unparseable input to allow graceful degradation

**Task 2: Add `DockerTotalMemorySensor` class**
- Inherit from `UnraidSensorEntity`
- Set `_attr_translation_key = "docker_total_memory"`
- Use `SensorDeviceClass.DATA_SIZE`, native unit bytes, suggested display unit
GiB
- Set `_attr_entity_registry_enabled_default = False`
- Accept `ws_manager` in the constructor, following the same pattern as
`ContainerMemoryUsageSensor`
- In `native_value`: iterate `ws_manager.container_stats.stats.values()`, call
`parse_docker_memory_string()` on each `memUsage`, sum valid results and return
total bytes

**Task 3: Add `DockerTotalMemoryUsageSensor` class**
- Inherit from `UnraidSensorEntity`
- Set `_attr_translation_key = "docker_total_memory_usage"`
- Use percentage unit with `SensorStateClass.MEASUREMENT`
- Set `_attr_entity_registry_enabled_default = False`
- Accept both `ws_manager` and `coordinator` in the constructor
- In `native_value`: compute total Docker bytes using
`parse_docker_memory_string()`, divide by `data.metrics.memory_total`, multiply
by 100; return `None` if no container stats or system data is unavailable

**Task 4: Update `strings.json` and `icons.json`**
- In `custom_components/unraid/strings.json` under `entity.sensor`, add:
  - `docker_total_memory`: `{ "name": "Docker total memory" }`
  - `docker_total_memory_usage`: `{ "name": "Docker total memory usage" }`
- In `custom_components/unraid/icons.json` under `entity.sensor`, add:
  - `docker_total_memory`: `{ "default": "mdi:docker" }`
  - `docker_total_memory_usage`: `{ "default": "mdi:docker" }`

**Task 5: Register sensors in `async_setup_entry`**
- In `custom_components/unraid/sensor.py`, locate `async_setup_entry` and after
the per-container sensor loop (around line 2660), instantiate
`DockerTotalMemorySensor` and `DockerTotalMemoryUsageSensor`
- Only instantiate if `system_coordinator.data` is available and Docker is
enabled (containers list exists)
- Pass `system_coordinator`, `server_uuid`, `server_name`, and `ws_manager` to
the constructors

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!