Skip to content

feat: add vmstat builtin for host memory/CPU/IO pressure investigation#557

Draft
Hitsuji-M wants to merge 4 commits into
mainfrom
erwann.masson/builtin-vmstat
Draft

feat: add vmstat builtin for host memory/CPU/IO pressure investigation#557
Hitsuji-M wants to merge 4 commits into
mainfrom
erwann.masson/builtin-vmstat

Conversation

@Hitsuji-M

Copy link
Copy Markdown

Summary

  • Add a vmstat builtin for host memory/CPU/IO pressure investigation, mirroring the existing df/ss architecture.
  • Linux reads /proc/{stat,meminfo,vmstat,loadavg,uptime} directly (sandbox-exempt, same pattern as ss/ip route/df).
  • macOS reads via sysctl(3) (hw.memsize, vm.swapusage, vm.loadavg) using the existing darwin toolset, not Mach host_statistics64; unavailable columns render as 0/- rather than being fabricated.
  • Windows/other platforms report "not supported".
  • Supports three modes: default snapshot, vmstat DELAY [COUNT] sampling, and -s/--stats full counter summary, plus -a, -w, -S k|K|m|M, -h/--help.
  • Updates analysis/symbols_builtins.go and analysis/symbols_internal.go allowlists, SHELL_FEATURES.md, README.md, and AGENTS.md security design decisions.

Test plan

  • make fmt / gofmt -l . clean
  • go test ./analysis/... ./builtins/... ./tests/...
  • Black-box tests over synthetic /proc fixtures (builtins/tests/vmstat/vmstat_linux_test.go, run via Docker golang:1.25)
  • Scenario tests under tests/scenarios/cmd/vmstat/ (all skip_assert_against_bash: true — vmstat isn't in debian:bookworm-slim and output is host-state-dependent)
  • Manual verification on macOS: default snapshot, -a, -w, -s, --help

Comment thread builtins/vmstat/vmstat.go Dismissed
@Hitsuji-M Hitsuji-M self-assigned this Jul 17, 2026
@Hitsuji-M
Hitsuji-M force-pushed the erwann.masson/builtin-vmstat branch from 2a09b7e to 49bbf62 Compare July 17, 2026 12:28

@matt-dz matt-dz left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks good for the most part. however, i recommend running a review loop with codex -- it catches more in-the-weeds issues with the builtin logic

// readImpl returns ErrNotSupported on platforms without a backend
// (Windows and anything else). Mirrors diskstats_other.go.
func readImpl(_ context.Context, _ string) (Stats, error) {
return Stats{}, ErrNotSupported

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what's the reason for not supporting windows? asking because i'm unfamiliar with the platform and want to understand the decision

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants