Reference

Server and agent flags, HTTP API endpoints, supported perf events, and the usual things to check when something looks off.

Server CLI

Agent CLI

The agent runs in one of three modes — pick one.

Common options:

HTTP API

Supported perf events

The agent probes each event before use and only emits the ones the kernel actually supports. On hybrid CPUs, events are reported per-cluster — e.g. cpu_core/cycles/ and cpu_atom/cycles/.

Building release packages

./build_package.sh              # frozen server + agent (PyInstaller)
./build_package.sh --server     # server only
./build_package.sh --agent      # agent only
./build_package.sh --no-freeze  # skip PyInstaller, ship raw Python

Outputs land in dist/:

dist/
├── perflens-server-<ver>.tar.gz
└── perflens-agent-<ver>.tar.gz

Drop cross-compiled binaries into server/bin/ and agent/bin/<arch>/ before building for fully self-contained tarballs. The agent launcher auto-prepends the correct arch directory to $PATH based on uname -m; if a bundled binary is missing, agent and server fall back to system tools.

CI

.github/workflows/build.yml builds the server on three runners (Linux, macOS arm64, Windows), the Python agent once on Linux, and the C agent for five architectures (x86_64, aarch64, aarch64_be, armv7l, armeb). Big-endian targets use musl toolchains from musl.cc since Ubuntu only ships little-endian sysroots. Tagged pushes (v*) create a GitHub Release and attach every tarball.

Troubleshooting

perf_event_paranoid too high

The agent warns at startup if /proc/sys/kernel/perf_event_paranoid > 1 and the UI may show a limited event set.

sudo sysctl -w kernel.perf_event_paranoid=1

No function names

Compile with -g and don't strip. file ./myprogram should say not stripped and with debug_info.

No source line mapping

Double-check --binary points at the exact unstripped binary running on the target and --source-dir contains the source files. If the build root differs from your checkout, rewrite paths with --path-map /build/src=/home/me/src.

Agent can't connect

The server must be reachable on --port. Sanity-check with nc -zv <server-ip> 9999.

LXC / container: perf record -p <pid> returns empty

Some container environments strip the perf capability set. A system-wide perf record -a usually works; the agent's per-PID mode does not in that case.

Call-graph probing hangs / slow startup

Capability probing tests fp, dwarf, then lbr in sequence — this adds ~6–12 seconds on first connection. One-time cost; subsequent rounds skip probing.

Project layout

perflens/
├── agent/
│   └── perflens_agent.py         # Python 3.5+ device agent
├── agent-c/
│   ├── perflens_agent.c          # C agent, static binary, zero deps
│   ├── Makefile                  # native + cross-compile targets
│   └── vendor/zstd/              # vendored zstd amalgamation
├── server/
│   ├── perflens_server.py        # TCP listener + ThreadingHTTPServer
│   ├── parser.py                 # perf script / perf stat parser
│   ├── source_mapper.py          # addr2line pipeline + path remap
│   └── bin/                      # bundled zstd / addr2line / readelf
├── ui/
│   ├── index.html                # single-page app
│   ├── app.js                    # all UI logic (vanilla JS)
│   └── style.css                 # dark + light themes
├── test/
│   ├── sample_workload.c
│   └── Makefile
├── build_package.sh
└── .github/workflows/build.yml