Skip to main content

Module trace

supermachine

Module trace 

Source
Expand description

Unified TRACE category gate (0.7.39+).

Before 0.7.39 each subsystem checked its own env var: SUPERMACHINE_BAKE_TRACE, SUPERMACHINE_VFS_TRACE, SUPERMACHINE_BALLOON_TRACE, … — fourteen separate knobs. Discoverability was poor and the env-var surface area was sprawling.

The new shape is one variable, comma-separated categories:

SUPERMACHINE_TRACE=bake,vfs           # those two categories
SUPERMACHINE_TRACE=all                # everything
SUPERMACHINE_TRACE=*                  # synonym for "all"
SUPERMACHINE_TRACE=1                  # legacy: also "all"

Legacy SUPERMACHINE_<CAT>_TRACE (and the SUPERMACHINE_TIMINGS/SUPERMACHINE_REMAP_TIMINGS variants) still work for one release as a deprecation runway.

Categories (lowercase):

  • bake — bake pipeline stages
  • vfs — drop_vfs_caches RPC + per-restore VFS hooks
  • balloon — virtio-balloon inflate / deflate
  • fuse — per-FUSE-op log (virtio-fs daemon)
  • tls — router TLS handshake
  • vq — virtio queue events
  • vsock — virtio-vsock muxer
  • router — router worker-selection
  • remap — KVM memory remap timings during restore
  • rosetta — amd64-on-arm64 Rosetta ioctl events
  • timeout — exec timeout firing + kill latency
  • timings — spawn_one / acquire / coord timings
  • run — supermachine run CLI lifecycle

Cost: one OnceLock-cached HashSet lookup per call. Sub-µs. Safe to call from hot paths gated behind if trace::enabled("x").

Functions§

enabled
True iff the category (or “all”) is currently enabled. Use at every site that previously checked std::env::var_os(...).
fuse_target
FUSE trace’s existing shape is SUPERMACHINE_FUSE_TRACE=PATH where the value is a target file path (not just a boolean). This helper preserves that — returns the path when set OR returns the unified-var equivalent when fuse is in the category set (falling back to a sentinel path the caller resolves).