@devries-cameron20 / t3code Mirror · read-only
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, 03:37 UTC

main
md 57 lines 3.51 KB
Rendered Raw
1 # Resource telemetry
2
3 Process counters come from a [standalone Rust monitor](../../native/resource-monitor/src/main.rs)
4 using `sysinfo`. Electron main supplies host power and Electron process metrics.
5 Keeping native collection outside Node isolates collector crashes and avoids a
6 Node/Electron addon ABI matrix. Desktop and CLI servers use the same child-process
7 protocol. A missing or failed collector leaves the server running.
8
9 ## Collection cost
10
11 The native child owns sampling and bounded in-memory history. It samples on a timer
12 only while diagnostics has live subscribers. With none, the server sends a sample
13 interval of 0 and the child samples only on request, so an idle server never walks
14 the process table. The exception is OTLP metrics export: a server exporting metrics
15 requests one sample a minute and exports process totals by group
16 ([`ProcessGroupMetrics`](../../apps/server/src/resourceTelemetry/ProcessGroupMetrics.ts)),
17 because the user asked for continuous telemetry. Groups are a fixed set named after
18 the server's direct children, never process IDs or threads, so the series count
19 stays bounded as agents come and go. History therefore covers only time with a live
20 subscriber, plus on-demand and export samples. Consuming host power for background scheduling must not retain
21 live diagnostics. There is no telemetry database or recurring shell-probe fallback.
22
23 History has independent bounds for age, snapshot count, process rows, and retained
24 bytes. A count limit alone cannot bound memory when command lines vary in size.
25 Large process trees therefore shorten the available history window. Linux task
26 enumeration is disabled because walking every `/proc/<pid>/task/<tid>` directory
27 makes sampling itself expensive.
28
29 Electron power updates travel over private inherited pipes, independent of the
30 renderer connection. Power events and slow heartbeats continue with diagnostics
31 closed; `app.getAppMetrics()` runs only on live demand. The receiver's stale deadline
32 must exceed the slowest configured heartbeat plus scheduling grace, or intentional
33 idle polling makes background policy oscillate between constrained and
34 unconstrained states. Headless servers leave unavailable power data unknown.
35
36 ## Measurement traps
37
38 - Process identity includes start time because operating systems reuse PIDs.
39 Electron and native start times have different precision, so merging allows a
40 small tolerance. Process signaling rechecks the native identity with a fresh
41 sample.
42 - Snapshot sequence numbers belong to a monitor generation. Comparing them across
43 restarts would discard the new monitor's samples until its sequence caught up.
44 - Sampling can miss a process that starts and exits between samples. Cumulative
45 counters still yield deltas for processes observed across samples.
46 - Windows process I/O includes more than disk traffic. Unix counters report storage
47 I/O, which can differ from logical application reads and writes because of OS
48 caching. Keep instrumented logical I/O separate from these counters.
49 - Group totals accumulate observed deltas since telemetry started. Per-process
50 cumulative counters cover the operating system's lifetime for that process.
51 - Historical replay uses native samples without current Electron CPU or memory
52 metrics. Merging the latest Electron values would overwrite the past.
53
54 A WSL backend needs a Linux monitor even though Electron runs on Windows. Windows
55 desktop packages currently supply only the Windows executable, so native process
56 telemetry for the WSL backend is unavailable. The inherited Electron power feed
57 still works.