@devries-cameron20 / t3code Mirror · read-only / commits / 4ea32cb62e
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 21:00 UTC

fix(server): load balancing reads container cgroup limits instead of the host's (#28261)

Julius Marminge committed Nov 11, 2026 at 15:47 UTC 4ea32cb62e4241891c6e1096f0d868e5548da6de
2 files changed +337 -8
apps/server/src/resourceTelemetry/HostResources.test.ts new
+227
@@ -0,0 +1,227 @@
1 +import { assert, describe, it } from "@effect/vitest";
2 +import type * as NodeOS from "node:os";
3 +import * as HostProcess from "@t3tools/shared/HostProcess";
4 +import * as Effect from "effect/Effect";
5 +import * as Fiber from "effect/Fiber";
6 +import * as FileSystem from "effect/FileSystem";
7 +import * as Layer from "effect/Layer";
8 +import * as PlatformError from "effect/PlatformError";
9 +import { ChildProcessSpawner } from "effect/process";
10 +import * as TestClock from "effect/testing/TestClock";
11 +import { vi } from "vite-plus/test";
12 +
13 +import * as HostResources from "./HostResources.ts";
14 +
15 +// An 8-CPU host; every cpus() call advances each CPU by 100 ms at `host.busy` utilization.
16 +const host = vi.hoisted(() => ({ busy: 0, reads: 0 }));
17 +vi.mock("node:os", async (importOriginal) => {
18 + const actual = await importOriginal<typeof NodeOS>();
19 + return {
20 + ...actual,
21 + totalmem: () => 4 * 1024 ** 3,
22 + cpus: () => {
23 + const elapsed = 100 * host.reads++;
24 + const times = {
25 + user: elapsed * host.busy,
26 + nice: 0,
27 + sys: 0,
28 + idle: elapsed * (1 - host.busy),
29 + irq: 0,
30 + };
31 + return Array.from({ length: 8 }, () => ({ model: "test", speed: 1, times }));
32 + },
33 + };
34 +});
35 +const setup = (busy = 0) => {
36 + host.busy = busy;
37 + host.reads = 0;
38 +};
39 +
40 +const GiB = 1024 ** 3;
41 +const MiB = 1024 ** 2;
42 +const cgroup = "/sys/fs/cgroup/t3.slice/server.scope";
43 +const unlimitedCgroup = {
44 + "/proc/self/cgroup": ["0::/t3.slice/server.scope\n"],
45 + "/proc/meminfo": [`MemTotal: ${4 * 1024 * 1024} kB\nMemAvailable: ${2 * 1024 * 1024} kB\n`],
46 + [`${cgroup}/cpu.max`]: ["max 100000\n"],
47 + [`${cgroup}/cpu.stat`]: ["usage_usec 5000000\n"],
48 + [`${cgroup}/memory.max`]: ["max\n"],
49 + [`${cgroup}/memory.current`]: [`${600 * MiB}\n`],
50 + [`${cgroup}/memory.stat`]: [`anon ${450 * MiB}\ninactive_file ${100 * MiB}\n`],
51 +};
52 +
53 +// Each path serves its values in order and repeats the last one.
54 +const linuxHost = (files: Record<string, ReadonlyArray<string>>) => {
55 + const reads = new Map<string, number>();
56 + return HostResources.layer.pipe(
57 + Layer.provide(
58 + Layer.mergeAll(
59 + FileSystem.layerNoop({
60 + readFileString: (path) => {
61 + const values = files[path];
62 + if (!values) {
63 + return Effect.fail(
64 + PlatformError.systemError({
65 + _tag: "NotFound",
66 + module: "FileSystem",
67 + method: "readFileString",
68 + pathOrDescriptor: path,
69 + }),
70 + );
71 + }
72 + const index = reads.get(path) ?? 0;
73 + reads.set(path, index + 1);
74 + return Effect.succeed(values[Math.min(index, values.length - 1)]!);
75 + },
76 + }),
77 + Layer.succeed(HostProcess.Platform, "linux"),
78 + Layer.succeed(
79 + ChildProcessSpawner.ChildProcessSpawner,
80 + ChildProcessSpawner.make(() => Effect.die("HostResources spawned on linux")),
81 + ),
82 + ),
83 + ),
84 + );
85 +};
86 +
87 +const read = Effect.gen(function* () {
88 + const host = yield* HostResources.HostResources;
89 + const fiber = yield* Effect.forkChild(host.read);
90 + yield* TestClock.adjust("200 millis");
91 + return yield* Fiber.join(fiber);
92 +});
93 +
94 +describe("HostResources.layer", () => {
95 + it.effect("reports the CPU quota and usage of the server's cgroup", () =>
96 + Effect.gen(function* () {
97 + setup();
98 + const snapshot = yield* read;
99 +
100 + // One CPU of quota, 150 ms of it used during the 200 ms sample.
101 + assert.strictEqual(snapshot.cpuCount, 1);
102 + assert.strictEqual(snapshot.cpuUtilization, 0.75);
103 + }).pipe(
104 + Effect.provide(
105 + linuxHost({
106 + ...unlimitedCgroup,
107 + [`${cgroup}/cpu.max`]: ["100000 100000\n"],
108 + [`${cgroup}/cpu.stat`]: [
109 + "usage_usec 5000000\nuser_usec 4000000\nsystem_usec 1000000\n",
110 + "usage_usec 5150000\nuser_usec 4100000\nsystem_usec 1050000\n",
111 + ],
112 + }),
113 + ),
114 + ),
115 + );
116 +
117 + it.effect("reports memory against the server cgroup's memory.max", () =>
118 + Effect.gen(function* () {
119 + setup();
120 + const snapshot = yield* read;
121 +
122 + assert.strictEqual(snapshot.totalMemoryBytes, GiB);
123 + // 600 MiB charged, of which 100 MiB is reclaimable page cache.
124 + assert.strictEqual(snapshot.availableMemoryBytes, GiB - 500 * MiB);
125 + }).pipe(
126 + Effect.provide(
127 + linuxHost({
128 + ...unlimitedCgroup,
129 + [`${cgroup}/memory.max`]: [`${GiB}\n`],
130 + }),
131 + ),
132 + ),
133 + );
134 +
135 + it.effect("counts a busy host against an idle, quota-limited server cgroup", () =>
136 + Effect.gen(function* () {
137 + // Agents in sibling cgroups keep the host 90% busy; the server's own cgroup is idle.
138 + setup(0.9);
139 + const snapshot = yield* read;
140 +
141 + assert.strictEqual(snapshot.cpuCount, 2);
142 + // Only 0.8 of 8 host CPUs are free, which is 60% of the 2-CPU quota in use.
143 + assert.closeTo(snapshot.cpuUtilization ?? Number.NaN, 0.6, 1e-9);
144 + }).pipe(
145 + Effect.provide(
146 + linuxHost({
147 + ...unlimitedCgroup,
148 + [`${cgroup}/cpu.max`]: ["200000 100000\n"],
149 + }),
150 + ),
151 + ),
152 + );
153 +
154 + it.effect("samples the CPUs the server is pinned to by id, not by os.cpus() index", () =>
155 + Effect.gen(function* () {
156 + setup();
157 + const snapshot = yield* read;
158 +
159 + assert.strictEqual(snapshot.cpuCount, 1);
160 + assert.strictEqual(snapshot.cpuUtilization, 1);
161 + }).pipe(
162 + Effect.provide(
163 + linuxHost({
164 + ...unlimitedCgroup,
165 + "/proc/self/status": ["Name:\tnode\nCpus_allowed_list:\t4\n"],
166 + // CPU 1 is offline; the server's CPU 4 is saturated, everything else is idle.
167 + "/proc/stat": [0, 100].map((elapsed) =>
168 + [0, 2, 3, 4, 5, 6, 7]
169 + .map((id) =>
170 + id === 4
171 + ? `cpu${id} ${elapsed} 0 0 0 0 0 0 0`
172 + : `cpu${id} 0 0 0 ${elapsed} 0 0 0 0`,
173 + )
174 + .join("\n"),
175 + ),
176 + }),
177 + ),
178 + ),
179 + );
180 +
181 + it.effect("keeps host memory when the cgroup's memory.current is unreadable", () =>
182 + Effect.gen(function* () {
183 + setup();
184 + const snapshot = yield* read;
185 +
186 + assert.strictEqual(snapshot.totalMemoryBytes, 4 * GiB);
187 + assert.strictEqual(snapshot.availableMemoryBytes, 2 * GiB);
188 + }).pipe(
189 + Effect.provide(
190 + linuxHost({
191 + ...unlimitedCgroup,
192 + [`${cgroup}/memory.max`]: [`${GiB}\n`],
193 + [`${cgroup}/memory.current`]: [""],
194 + }),
195 + ),
196 + ),
197 + );
198 +
199 + it.effect("keeps host values when the cgroup has no limits", () =>
200 + Effect.gen(function* () {
201 + setup(0.25);
202 + const snapshot = yield* read;
203 +
204 + assert.strictEqual(snapshot.cpuCount, 8);
205 + assert.closeTo(snapshot.cpuUtilization ?? Number.NaN, 0.25, 1e-9);
206 + assert.strictEqual(snapshot.availableMemoryBytes, 2 * GiB);
207 + }).pipe(Effect.provide(linuxHost(unlimitedCgroup))),
208 + );
209 +
210 + it.effect("falls back to host load when the cgroup's cpu.stat is unreadable", () =>
211 + Effect.gen(function* () {
212 + setup(0.9);
213 + const snapshot = yield* read;
214 +
215 + assert.strictEqual(snapshot.cpuCount, 2);
216 + assert.closeTo(snapshot.cpuUtilization ?? Number.NaN, 0.6, 1e-9);
217 + }).pipe(
218 + Effect.provide(
219 + linuxHost({
220 + ...unlimitedCgroup,
221 + [`${cgroup}/cpu.max`]: ["200000 100000\n"],
222 + [`${cgroup}/cpu.stat`]: [""],
223 + }),
224 + ),
225 + ),
226 + );
227 +});
apps/server/src/resourceTelemetry/HostResources.ts
+110 -8
@@ -2,6 +2,7 @@ import * as NodeOS from "node:os";
2 import type { HostResourcesSnapshot } from "@t3tools/contracts";
3 import * as HostProcess from "@t3tools/shared/HostProcess";
4 import * as Cache from "effect/Cache";
5 +import * as Clock from "effect/Clock";
6 import * as Context from "effect/Context";
7 import * as DateTime from "effect/DateTime";
8 import * as Effect from "effect/Effect";
@@ -14,6 +15,33 @@ export class HostResources extends Context.Service<
15 { readonly read: Effect.Effect<HostResourcesSnapshot> }
16 >()("t3/resourceTelemetry/HostResources") {}
17
18 +// Linux CPU list syntax, as in Cpus_allowed_list: "0-3,8,10-11".
19 +function parseCpuList(list: string): ReadonlySet<number> | null {
20 + const cpus = new Set<number>();
21 + for (const range of list.split(",")) {
22 + const match = /^(\d+)(?:-(\d+))?$/.exec(range.trim());
23 + if (!match) return null;
24 + for (let cpu = Number(match[1]); cpu <= Number(match[2] ?? match[1]); cpu++) cpus.add(cpu);
25 + }
26 + return cpus;
27 +}
28 +
29 +// os.cpus() compacts online CPUs, so its indices are not CPU ids; /proc/stat lines are keyed.
30 +function pinnedCpu(stat: string, allowed: ReadonlySet<number>) {
31 + const cpu = { idle: 0, total: 0, count: 0 };
32 + for (const [, id, fields] of stat.matchAll(/^cpu(\d+) (.+)$/gm)) {
33 + if (!allowed.has(Number(id))) continue;
34 + const counters = (fields ?? "").trim().split(/\s+/).map(Number);
35 + const at = (index: number) => counters[index] ?? 0;
36 + // user nice system idle iowait irq softirq steal
37 + const idle = at(3) + at(4);
38 + cpu.idle += idle;
39 + cpu.total += idle + at(0) + at(1) + at(2) + at(5) + at(6) + at(7);
40 + cpu.count++;
41 + }
42 + return cpu.count > 0 ? cpu : null;
43 +}
44 +
45 function readCpu() {
46 const cpus = NodeOS.cpus();
47 const cpu = cpus.reduce(
@@ -37,28 +65,84 @@ function darwinAvailableMemory(output: string): number | null {
65 return Number.isSafeInteger(available) && Number(pageSize) > 0 ? available : null;
66 }
67
68 +function cgroupNumber(text: string, pattern: RegExp): number | null {
69 + const value = pattern.exec(text)?.[1];
70 + return value === undefined ? null : Number(value);
71 +}
72 +
73 const make = Effect.fn("makeHostResources")(function* () {
74 const fs = yield* FileSystem.FileSystem;
75 const platform = yield* HostProcess.Platform;
76 const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
77
78 + const readFile = (path: string) => fs.readFileString(path).pipe(Effect.orElseSucceed(() => ""));
79 +
80 const sample = Effect.fn("HostResources.sample")(function* () {
46 - const previousCpu = readCpu();
81 + // cgroup v2 only; limits of the server's own cgroup, which is `/` inside a container.
82 + const cgroupPath =
83 + platform === "linux"
84 + ? /^0::(\/.*)$/m.exec(yield* readFile("/proc/self/cgroup"))?.[1]
85 + : undefined;
86 + const cgroup =
87 + cgroupPath === undefined ? null : `/sys/fs/cgroup${cgroupPath.replace(/\/$/, "")}`;
88 + const cpuMax = cgroup
89 + ? /^(\d+) (\d+)$/.exec((yield* readFile(`${cgroup}/cpu.max`)).trim())
90 + : null;
91 + const readCpuUsage = () =>
92 + cpuMax
93 + ? Effect.map(readFile(`${cgroup}/cpu.stat`), (stat) =>
94 + cgroupNumber(stat, /^usage_usec (\d+)$/m),
95 + )
96 + : Effect.succeed(null);
97 + // Affinity (cpuset) pins the server to some CPUs; idle CPUs outside it are of no use.
98 + const allowedCpus =
99 + platform === "linux"
100 + ? parseCpuList(
101 + /^Cpus_allowed_list:\s*(\S+)$/m.exec(yield* readFile("/proc/self/status"))?.[1] ?? "",
102 + )
103 + : null;
104 +
105 + const sampleCpu = () =>
106 + allowedCpus
107 + ? Effect.map(readFile("/proc/stat"), (stat) => pinnedCpu(stat, allowedCpus) ?? readCpu())
108 + : Effect.sync(readCpu);
109 +
110 + const previousCpu = yield* sampleCpu();
111 + const previousUsage = yield* readCpuUsage();
112 + const startedAt = yield* Clock.currentTimeMillis;
113 yield* Effect.sleep("200 millis");
48 - const cpu = readCpu();
114 + const cpu = yield* sampleCpu();
115 + const usage = yield* readCpuUsage();
116 + const elapsedMicros = ((yield* Clock.currentTimeMillis) - startedAt) * 1000;
117 const totalDelta = cpu.total - previousCpu.total;
118 const idleDelta = cpu.idle - previousCpu.idle;
51 - const cpuUtilization =
119 + let cpuCount = cpu.count;
120 + const hostUtilization =
121 previousCpu.count === cpu.count && totalDelta > 0 && idleDelta >= 0
122 ? Math.min(1, Math.max(0, 1 - idleDelta / totalDelta))
123 : null;
55 - const totalMemoryBytes = NodeOS.totalmem();
124 + let cpuUtilization = hostUtilization;
125 + if (cpuMax) {
126 + const capacity = Math.min(Number(cpuMax[1]) / Number(cpuMax[2]), cpu.count);
127 + cpuCount = Math.max(1, Math.floor(capacity));
128 + const cgroupIdle =
129 + previousUsage !== null && usage !== null && elapsedMicros > 0
130 + ? capacity - (usage - previousUsage) / elapsedMicros
131 + : null;
132 + // Agents can run in sibling cgroups (agentScope.ts), so a busy host still counts.
133 + const hostIdle = hostUtilization === null ? null : cpu.count * (1 - hostUtilization);
134 + const idle =
135 + cgroupIdle === null || hostIdle === null
136 + ? (cgroupIdle ?? hostIdle)
137 + : Math.min(cgroupIdle, hostIdle);
138 + cpuUtilization = idle === null ? null : Math.min(1, Math.max(0, 1 - idle / capacity));
139 + }
140 +
141 + let totalMemoryBytes = NodeOS.totalmem();
142 // On Windows libuv returns GlobalMemoryStatusEx.ullAvailPhys, including standby memory.
143 let availableMemoryBytes = NodeOS.freemem();
144 if (platform === "linux") {
59 - const meminfo = yield* fs
60 - .readFileString("/proc/meminfo")
61 - .pipe(Effect.orElseSucceed(() => ""));
145 + const meminfo = yield* readFile("/proc/meminfo");
146 const available = /^MemAvailable:\s+(\d+)\s+kB$/m.exec(meminfo)?.[1];
147 if (available) availableMemoryBytes = Number(available) * 1024;
148 } else if (platform === "darwin") {
@@ -70,10 +154,28 @@ const make = Effect.fn("makeHostResources")(function* () {
154 );
155 availableMemoryBytes = darwinAvailableMemory(output) ?? availableMemoryBytes;
156 }
157 + const memoryMax = cgroup
158 + ? cgroupNumber(yield* readFile(`${cgroup}/memory.max`), /^(\d+)$/m)
159 + : null;
160 + const memoryCurrent =
161 + memoryMax === null
162 + ? null
163 + : cgroupNumber(yield* readFile(`${cgroup}/memory.current`), /^(\d+)$/m);
164 + // Without usage, a capped total would read as a near-empty cgroup; keep host values instead.
165 + if (memoryMax !== null && memoryCurrent !== null) {
166 + totalMemoryBytes = Math.min(totalMemoryBytes, memoryMax);
167 + // inactive_file is page cache the kernel reclaims before hitting memory.max.
168 + const stat = yield* readFile(`${cgroup}/memory.stat`);
169 + const reclaimable = cgroupNumber(stat, /^inactive_file (\d+)$/m) ?? 0;
170 + availableMemoryBytes = Math.min(
171 + availableMemoryBytes,
172 + memoryMax - (memoryCurrent - reclaimable),
173 + );
174 + }
175 return {
176 sampledAt: DateTime.toEpochMillis(yield* DateTime.now),
177 cpuUtilization,
76 - cpuCount: cpu.count,
178 + cpuCount,
179 availableMemoryBytes: Math.min(totalMemoryBytes, Math.max(0, availableMemoryBytes)),
180 totalMemoryBytes,
181 };