Open History to see the last commit
1import * as NodeOS from "node:os";
2import type { HostResourcesSnapshot } from "@t3tools/contracts";
3import * as HostProcess from "@t3tools/shared/HostProcess";
4import * as Cache from "effect/Cache";
5import * as Clock from "effect/Clock";
6import * as Context from "effect/Context";
7import * as DateTime from "effect/DateTime";
8import * as Effect from "effect/Effect";
9import * as FileSystem from "effect/FileSystem";
10import * as Layer from "effect/Layer";
11import { ChildProcess, ChildProcessSpawner } from "effect/process";
12
13export class HostResources extends Context.Service<
14 HostResources,
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".
19function 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.
30function 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
45function readCpu() {
46 const cpus = NodeOS.cpus();
47 const cpu = cpus.reduce(
48 (sum, { times }) => ({
49 idle: sum.idle + times.idle,
50 total: sum.total + times.user + times.nice + times.sys + times.idle + times.irq,
51 }),
52 { idle: 0, total: 0 },
53 );
54 return { ...cpu, count: cpus.length };
55}
56
57function darwinAvailableMemory(output: string): number | null {
58 const pageSize = /page size of (\d+) bytes/.exec(output)?.[1];
59 const free = /^Pages free:\s+(\d+)\./m.exec(output)?.[1];
60 const inactive = /^Pages inactive:\s+(\d+)\./m.exec(output)?.[1];
61 const speculative = /^Pages speculative:\s+(\d+)\./m.exec(output)?.[1];
62 if (!pageSize || !free || !inactive || !speculative) return null;
63 // vm_stat excludes speculative from free; add it once, without overlapping purgeable pages.
64 const available = (Number(free) + Number(inactive) + Number(speculative)) * Number(pageSize);
65 return Number.isSafeInteger(available) && Number(pageSize) > 0 ? available : null;
66}
67
68function cgroupNumber(text: string, pattern: RegExp): number | null {
69 const value = pattern.exec(text)?.[1];
70 return value === undefined ? null : Number(value);
71}
72
73const 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* () {
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");
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;
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;
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") {
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") {
149 const output = yield* spawner
150 .string(ChildProcess.make("/usr/bin/vm_stat", [], { stdin: "ignore", stderr: "ignore" }))
151 .pipe(
152 Effect.timeout("1 second"),
153 Effect.orElseSucceed(() => ""),
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,
178 cpuCount,
179 availableMemoryBytes: Math.min(totalMemoryBytes, Math.max(0, availableMemoryBytes)),
180 totalMemoryBytes,
181 };
182 });
183
184 const cache = yield* Cache.make({
185 capacity: 1,
186 lookup: (_key: "host") => sample(),
187 timeToLive: "5 seconds",
188 });
189 return HostResources.of({ read: Cache.get(cache, "host") });
190});
191
192export const layer = Layer.effect(HostResources, make());