fix(docker): report container CPU as a total-system percentage (0-100%)

Drop the docker-stats per-core convention (* online_cpus), which produced
readings like 134% and surprised users. system_cpu_usage accumulates across
all cores, so the plain delta ratio is the share of the whole machine - the
same 0-100% scale the Unraid integration now reports, keeping CPU readings
consistent across homarr.

Author: junkerderprovinz

packages/request-handler/src/docker.ts

@@ -335,13 +335,25 @@ export function calculateCpuUsage(stats: ContainerStats): number {
     return 0;
   }
 
-  const numberOfCpus = stats.cpu_stats.online_cpus;
-  const usage = stats.cpu_stats.system_cpu_usage;
-  if (!usage || usage === 0) {
+  // Instantaneous CPU usage: compare the latest reading against the previous one
+  // (precpu_stats). Dividing the cumulative total_usage by the cumulative
+  // system_cpu_usage instead would report the container's lifetime average, which
+  // stays high long after a load spike has ended. precpu_stats is only present
+  // when the stats are NOT fetched in one-shot mode; when it is absent (e.g.
+  // Podman) the deltas fall back to the cumulative totals.
+  const cpuDelta = stats.cpu_stats.cpu_usage.total_usage - (stats.precpu_stats?.cpu_usage?.total_usage ?? 0);
+  const systemDelta = (stats.cpu_stats.system_cpu_usage ?? 0) - (stats.precpu_stats?.system_cpu_usage ?? 0);
+
+  if (systemDelta <= 0 || cpuDelta < 0) {
     return 0;
   }
 
-  return (stats.cpu_stats.cpu_usage.total_usage / usage) * numberOfCpus * 100;
+  // Report usage as a share of the WHOLE machine (0-100%), not docker-stats'
+  // per-core convention (which multiplies by online_cpus and can exceed 100%,
+  // e.g. "134%" for 1.34 busy cores). system_cpu_usage already accumulates
+  // across all cores, so the plain ratio is the total-system share. This keeps
+  // every CPU reading in homarr on the same intuitive 0-100% scale.
+  return (cpuDelta / systemDelta) * 100;
 }
 
 export function calculateMemoryUsage(stats: ContainerStats): number {

packages/request-handler/src/test/docker.spec.ts

@@ -64,16 +64,45 @@ describe("calculateCpuUsage", () => {
     const stats = createStats({
       cpu_stats: { online_cpus: 4, cpu_usage: { total_usage: 2000 }, system_cpu_usage: 10000 },
     });
-    // (2000 / 10000) * 4 * 100 = 80
-    expect(calculateCpuUsage(stats)).toBe(80);
+    // Total-system share: (2000 / 10000) * 100 = 20 (system_cpu_usage spans all cores)
+    expect(calculateCpuUsage(stats)).toBe(20);
   });
 
   test("should handle fractional CPU usage", () => {
     const stats = createStats({
       cpu_stats: { online_cpus: 2, cpu_usage: { total_usage: 500 }, system_cpu_usage: 100000 },
     });
-    // (500 / 100000) * 2 * 100 = 1
-    expect(calculateCpuUsage(stats)).toBe(1);
+    // (500 / 100000) * 100 = 0.5
+    expect(calculateCpuUsage(stats)).toBe(0.5);
+  });
+
+  test("should never exceed 100% even when multiple cores are fully busy", () => {
+    const stats = createStats({
+      // 3 of 4 cores fully busy: docker-stats' per-core convention would say 300%.
+      cpu_stats: { online_cpus: 4, cpu_usage: { total_usage: 7500 }, system_cpu_usage: 10000 },
+    });
+    // Total-system share: (7500 / 10000) * 100 = 75
+    expect(calculateCpuUsage(stats)).toBe(75);
+  });
+
+  test("should use the delta against precpu_stats for the current usage", () => {
+    const stats = createStats({
+      cpu_stats: { online_cpus: 4, cpu_usage: { total_usage: 1_002_000 }, system_cpu_usage: 20_000 },
+      precpu_stats: { cpu_usage: { total_usage: 1_000_000 }, system_cpu_usage: 10_000 },
+    });
+    // Despite a large lifetime total_usage, only the recent delta counts:
+    // (2000 / 10000) * 100 = 20
+    expect(calculateCpuUsage(stats)).toBe(20);
+  });
+
+  test("should report 0 for a container that was busy over its lifetime but is idle now", () => {
+    const stats = createStats({
+      cpu_stats: { online_cpus: 4, cpu_usage: { total_usage: 1_000_000 }, system_cpu_usage: 20_000 },
+      precpu_stats: { cpu_usage: { total_usage: 1_000_000 }, system_cpu_usage: 10_000 },
+    });
+    // No CPU delta since the last reading -> current usage is 0, even though the
+    // lifetime average would be high. This is the regression the fix addresses.
+    expect(calculateCpuUsage(stats)).toBe(0);
   });
 });