CPU profiling

Capture a profile

Build the development profiling binary and start your normal local workflow:

just profile-build
just run-cli

The profiling build samples CPU activity at 99 Hz and writes gzip-compressed pprof protobuf files below the active session’s profiling/ directory. The daemon writes periodic snapshots and keeps the newest eight daemon snapshots. When the daemon shuts down, Polytoken writes a final daemon snapshot before it closes telemetry and log output.

The development profiling binary also profiles the local conversation TUI when you attach to or start a local session. TUI snapshots use the tui-profile- filename prefix and share the session’s profiling/ directory. The TUI sampler starts after attachment reaches the conversation screen, so time spent in the session picker is not included. When you quit the TUI, Polytoken writes a final TUI snapshot after terminal teardown.

The profiling build is development-only. Normal and release builds do not start the sampler, open the console endpoints, or add the profiling libraries to the shipped binary.

Inspect the live task console

The profiling build exposes the daemon tokio-console server on 127.0.0.1:6669 and the local conversation TUI server on 127.0.0.1:6670. Connect a compatible tokio-console client to either loopback address while its process runs. Each server keeps approximately 60 seconds of task history. The console layer adds aggregation work to the runtime, so use it for diagnosis rather than routine operation.

Inspect a dump

A .pb.gz file contains the standard pprof protobuf wrapped in gzip. Decompress the file before passing it to a pprof-compatible viewer. For example:

gzip -dc "$DUMP" > profile.pb
go tool pprof -top profile.pb

The daemon’s feedback attachment picker labels its profile artifact CPU profile (pprof) and retrieves the newest snapshot through the daemon’s versioned artifact catalog. The serving daemon must also use a profiling build to refresh that catalog for TUI profile artifacts. If the picker does not list a TUI dump, restart the daemon with the profiling build, then reopen the attachment picker.

Polytoken sends diagnostic attachments, including an attached CPU profile, raw and unsanitized. A profile captured on your machine can contain symbolized stack frames with build-machine paths and internal symbol names. Review the attachment before you send it. See Crash Reporting and Feedback for the full attachment policy.

Expected overhead

The sampler runs at 99 Hz and normally contributes low single-digit CPU percentage overhead on a quiet development daemon. The task console adds additional aggregation cost that grows with task and span churn. A dump briefly pauses report generation while pprof collects samples, so a small sampling gap can appear around each snapshot. The profiler avoids common signal-safety risks by excluding libc, libgcc, pthread, and vdso frames from unwinding.

Each dump is an interval snapshot, not a whole-process history. A dump covers the time since the previous dump, so a manual dump or a shutdown dump splits what would otherwise be a full interval. Polytoken rebuilds the sampler after each dump, and samples that arrive while Polytoken encodes and writes the current dump are dropped rather than rolled into the next window. That short blind period keeps the profiler’s own encoding work out of the next dump. The dump written at shutdown covers only the tail since the previous dump, which can be a very short interval.

Treat these figures as operational guidance, not a benchmark guarantee. Repeat measurements on the workload and platform that matter to the investigation.