profile

Profile a VoidBox Process

Profile CPU, off-CPU, and hardware counters using the eBPF-based perf-agent tool.

Prerequisites

Tell the user FIRST before doing anything else:

perf-agent requires Linux capabilities to run without sudo. Please run:

sudo setcap 'cap_sys_admin,cap_bpf,cap_perfmon,cap_sys_ptrace,cap_checkpoint_restore=ep' $HOME/.local/bin/perf-agent

(Only needed once after each download.)

Note: The binary must NOT be on a nosuid filesystem (e.g. /tmp), as file capabilities are silently ignored there.

Do NOT attempt to run sudo yourself. Ask the user and wait for confirmation.

Setup

Run these checks yourself (no sudo needed):

1. Detect architecture and download if needed:

ARCH=$(uname -m)
case "$ARCH" in
  x86_64)  SUFFIX="linux-amd64" ;;
  aarch64) SUFFIX="linux-arm64" ;;
esac

mkdir -p "$HOME/.local/bin"

LATEST=$(curl -s https://api.github.com/repos/dpsoft/perf-agent/releases/latest | grep '"tag_name"' | cut -d'"' -f4)

if [ -x "$HOME/.local/bin/perf-agent" ]; then
  CURRENT=$("$HOME/.local/bin/perf-agent" --version 2>/dev/null || echo "unknown")
  if echo "$CURRENT" | grep -q "${LATEST#v}"; then
    echo "perf-agent up-to-date ($LATEST)"
  else
    echo "Downloading perf-agent $LATEST..."
    curl -fSL -o "$HOME/.local/bin/perf-agent" "https://github.com/dpsoft/perf-agent/releases/download/${LATEST}/perf-agent-${SUFFIX}"
    chmod +x "$HOME/.local/bin/perf-agent"
  fi
else
  echo "Downloading perf-agent $LATEST..."
  curl -fSL -o "$HOME/.local/bin/perf-agent" "https://github.com/dpsoft/perf-agent/releases/download/${LATEST}/perf-agent-${SUFFIX}"
  chmod +x "$HOME/.local/bin/perf-agent"
fi

After download or upgrade, ask the user to run the setcap command.

2. Verify Go (required for pprof analysis):

go version

Find the PID

Auto-detect the running voidbox process:

pgrep -fa voidbox

If multiple processes, pick the voidbox shell one. If none found, tell the user to start a voidbox process first.